Serving Own Services

    Use cds.serve in to construct service providers from the service definitions in corresponding CDS models. Subsequently, you can add [event handlers] to the constructed providers.

    By default, bootstrapping of servers is handled by the framework automatically. So, you only need cds.serve if you want to control the bootstrapping yourself, for example, in a custom express server.js.

    cds.serve… service(s)

    Initiates a fluent API chain to construct service providers; use the methods documented below to add more options.

    Common Usages:
    const { CatalogService } = await cds.serve ('my-services')
    const app = require('express')()
    cds.serve('all') .in (app)
    • name specifies which service to construct a provider for; use all to construct providers for all definitions found in the models.
    cds.serve('CatalogService')  //> serve a single service
    cds.serve('all')             //> serve all services found

    You may alternatively specify a string starting with './' or refer to a file name with a non-identifier character in it, like '-' below, as a convenient shortcut to serve all services from that model:

    cds.serve('./reviews-service')  //> is not an identifier through './'
    cds.serve('reviews-service')    //> same as '-', hence both act as:

    The method returns a fluent API object, which is also a Promise resolving to either an object with 'all' constructed service providers, or to the single one created in case you specified a single service:

    const { CatalogService, AdminService } = await cds.serve('all')
    const ReviewsService = await cds.serve('ReviewsService')

    The constructed service providers are cached in, which (a) makes them accessible to cds.connect, as well as (b) allows us to extend already constructed services through subsequent invocation of cds.serve.

    Common Usages and Defaults

    Most commonly, you’d use cds.serve in a custom file to add all the services to your express.js app as follows:

    const app = require('express')()

    This uses these defaults for all options:

    Option Description Default
    cds.serve … which services to construct 'all' services
     ↳  .from models to load definitions from './srv' folder
     ↳  .in express app to mount to — none —
     ↳  .to client protocol to serve to 'fiori'
     ↳  .at endpoint path to serve at @path or .name
     ↳  .with implementation function @impl or ._source.js

    Alternatively you can construct services individually, also from other models, and also mount them yourself, as document in the subsequent sections on individual fluent API options.

    If you just want to add some additional middleware, it’s recommended to bootstrap from a custom server.js.

     ↳  .from (model)

    Allows to determine the CDS models to fetch service definitions from, which can be specified as one of:

    • A filename of a single model, which gets loaded and parsed with [cds.load]
    • A name of a folder containing several models, also loaded with [cds.load]
    • The string 'all' as a shortcut for all models in the './srv' folder
    • An already parsed model in CSN format

    The latter allows you to [cds.load] or dynamically construct models yourself and pass in the CSN models, as in this example:

    const csn = await cds.load('my-services.cds')

    If omitted, './srv' is used as default.

     ↳  .to (protocol)

    Allows to specify the protocol through which to expose the service. Currently supported values are:

    • 'rest' plain http rest protocol without any OData-specific extensions
    • 'odata' standard OData rest protocol without any Fiori-specific extensions
    • 'fiori' OData protocol with all Fiori-specific extensions like Draft enabled

    If omitted, 'fiori' is used as default.

     ↳  .at (path)

    Allows to programmatically specify the mount point for the service.

    Note that this is only possible when constructing single services:

    cds.serve('all').at('/cat') //> error

    If omitted, the mount point is determined from annotation @path, if present, or from the service’s lowercase name, excluding trailing Service.

    service MyService @(path:'/cat'){...}  //> served at: /cat
    service CatalogService {...}           //> served at: /catalog

     ↳  .in (express app)

    Adds all service providers as routers to the given express app.

    const app = require('express')()

     ↳  .with (impl function)

    Allows to specify a function that adds [event handlers] to the service provider, either as a function or as a string referring to a separate node module containing the function.

    cds.serve('./srv/cat-service.cds') .with ('./srv/cat-service.js')
    cds.serve('./srv/cat-service') .with (srv => {
      srv.on ('READ','Books', (req) => req.reply([...]))

    Learn more about using impl annotations. Learn more about adding event handlers.

    Note that this is only possible when constructing single services:

    cds.serve('CatalogService') .with (srv=>{...})
    cds.serve('all') .with (srv=>{...})  //> error

    If omitted, an implementation is resolved from annotation @impl, if present, or from a .js file with the same basename than the CDS model, for example:

    service MyService @(impl:'cat-service.js'){...}
    srv/cat-service.cds  #> CDS model with service definition
    srv/cat-service.js   #> service implementation used by default
    Show/Hide Beta Features