Skip to content

    Protocol Adapters

    Protocol Adapters translate inbound requests and messages into instances of cds.Request and cds.Query.

    Default Configuration

    The protocol adapters are served at / and only the service prefix identifies the CDS service. The service prefix is either defined by @path or derived from the service name.

    Protocol Annotations

    If a service is annotated with @protocol, it’s only served at this protocol.


    The configuration of protocols must be done programmatically before bootstrapping the CDS services, for example, in a custom server.js.

    Remember to enable the beta feature for orchestration of express middlewares.

    If an additional protocol is configured, all services without the @protocol annotation are served for this protocol by default.

    OData V4

    cds.env.protocols = {
      'odata-v4': { path: '/odata-v4' }

    If AdminService is served additionally at this endpoint, the path is /odata-v4/admin.


    cds.env.protocols = {
      rest: { path: '/rest' }

    If AdminService is served additionally at this endpoint, the path is /rest/admin.

    GraphQL Adapter

    The GraphQL protocol adapter has reached an early general availability state and can be found in the package @cap-js/graphql on the default npm registry. Instructions on how to get started are included within the README of the public repository.

    cds.env.protocols = {
      graphql: { path: '/gql', impl: '@cap-js/graphql' }

    GraphQL Schema Using CLI

    The GraphQL schema can be generated stand-alone using cds compile -2 graphql.

    Custom Protocol Adapter

    Similar to the configuration of the GraphQL Adapter, you can plug in your own protocol. The impl property must point to the implementation of your protocol adapter. Additional options for the protocol adapter are provided on the same level.

    cds.env.protocols = {
      'custom-protocol': { path: '/custom', impl: '<custom-impl.js>', ...options }

    Current Limitations

    • Configuration of protocols must be done programmatically.
    • Additional protocols do not respect @protocol annotation yet.
    • The configured protocols do not show up in the index.html yet.