Providing Services​

This guide introduces how to define and implement services, leveraging generic implementations provided by the CAP runtimes, complemented by domain-specific custom logic.

Intro: Core Concepts​

The following sections give a brief overview of CAP's core concepts.

Service-Centric Paradigm​

A CAP application commonly provides services defined in CDS models and served by the CAP runtimes. Every active thing in CAP is a service. They embody the behavioral aspects of a domain in terms of exposed entities, actions, and events.

Ubiquitous Events​

At runtime, everything happening is in response to events. CAP features a ubiquitous notion of events, which represent both,requests coming in throughsynchronous APIs, as well asasynchronousevent messages, blurring the line between both worlds.

Event Handlers​

Service providers basically react on events in event handlers, plugged in to respective hooks provided by the core service runtimes.

Service Definitions​

Services as APIs​

In its most basic form, a service definition simply declares the data entities and operations it serves. For example:

service BookshopService {  entity Books {    keyID : UUID;    title  : String;    author : Association toAuthors;  }  entity Authors {    keyID : UUID;    name   : String;    books  : Association to manyBooks on books.author = $self;  }  action submitOrder (book: Books:ID, quantity: Integer);}

This definition effectively defines the API served byBookshopService.

Simple service definitions like that are all we need to run full-fledged servers out of the box, served by CAP's generic runtimes, without any implementation coding required.

Services as Facades​

In contrast to the all-in-one definition above, services usually expose views, aka projections, on underlying domain model entities:

using {sap.capire.bookshop as my }from '../db/schema';service BookshopService {  entity Books as projection on my.Books;  entity Authors as projection on my.Authors;  action submitOrder (book: Books:ID, quantity: Integer);}

This way, services become facades to encapsulated domain data, exposing different aspects tailored to respective use cases.

Denormalized Views​

Instead of exposing access to underlying data in a 1:1 fashion, services frequently expose denormalized views, tailored to specific use cases.

For example, the following service definition, undiscloses information about maintainers from end users and alsomarks the entities as@readonly:

using {sap.capire.bookshop as my }from '../db/schema';/** For serving end users */service CatalogService @(path:'/browse') {  /** For displaying lists of Books */  @readonly entity ListOfBooks as projection on Books  excluding {descr };  /** For display in details pages */  @readonly entity Books as projection on my.Books { *,    author.name as author  }excluding {createdBy,modifiedBy };}

Learn more aboutCQL the language used forprojections.See also: Prefer Single-Purposed Services!Find above sources incap/samples.

Auto-Exposed Entities​

Annotate entities with@cds.autoexpose to automatically include them in services containing entities with Association referencing to them. For example, this is commonly done for code list entities in order to serve Value Lists dropdowns on UIs:

service Zoo {  entity Foo {//...    code : Association toSomeCodeList;  }}@cds.autoexpose entity SomeCodeList {...}

Learn more about Auto-Exposed Entities in the CDS reference docs.

Redirected Associations​

When exposing related entities, associations are automatically redirected. This ensures that clients can navigate between projected entities as expected. For example:

service AdminService {  entity Books as projection on my.Books;  entity Authors as projection on my.Authors;  //> AdminService.Authors.books refers to AdminService.Books}

Learn more about Redirected Associations in the CDS reference docs.

Generic Providers​

The CAP runtimes forNode.js andJava provide a wealth of generic implementations, which serve most requests automatically, with out-of-the-box solutions to recurring tasks such as search, pagination, or input validation — the majority of this guide focuses on these generic features.

In effect, a service definitionas introduced above is all we need to run a full-fledged server out of the box. The need for coding reduces to real custom logic specific to a project's domain → sectionCustom Logic picks that up.

Serving CRUD Requests​

The CAP runtimes forNode.js andJava provide generic handlers, which automatically serve all CRUD requests to entities for CDS-modelled services on top of a defaultprimary database.

This comprises read and write operations like that:

• GET /Books/201 → reading single data entities
• GET /Books?... → reading data entity sets with advanced query options
• POST /Books {....} → creating new data entities
• PUT/PATCH /Books/201 {...} → updating data entities
• DELETE /Books/201 → deleting data entities

Deep Reads and Writes​

CDS and the runtimes have advanced support for modeling and serving document-oriented data. The runtimes provide generic handlers for serving deeply nested document structures out of the box as documented in here.

DeepREAD​

You can read deeply nested documents byexpanding along associations or compositions. For example, like this in OData:

GET .../Orders?$expand=header($expand=items)

SELECT.from ('Orders',o => {  o.ID, o.title, o.header (h => {    h.ID, h.status, h.items('*')  })})

Both would return an array of nested structures as follows:

[{    ID:1, title:'first order', header: {// to-one      ID:2, status:'open', items: [{// to-many        ID:3, description:'first order item'      },{        ID:4, description:'second order item'      }]    }  },  ...]

DeepINSERT​

Create a parent entity along with child entities in a single operation, for example, like that:

POST .../Orders {  ID:1, title: 'new order', header: {// to-one    ID:2,status:'open',items: [{// to-many      ID:3,description:'child of child entity'    },{      ID:4,description:'another child of child entity'    }]  }}

Note that Associations and Compositions are handled differently in (deep) inserts and updates:

• Compositions → runtimedeeply creates or updates entries in target entities
• Associations → runtimefills in foreign keys toexisting target entries

For example, the following request would create a newBook with areference to an existingAuthor, with{ID:12} being the foreign key value filled in for associationauthor:

POST .../Books {  ID:121, title: 'Jane Eyre', author: {ID:12}}

DeepUPDATE​

DeepUPDATE of the deeply nested documents look very similar to deepINSERT:

PUT .../Orders/1 {  title: 'changed title of existing order', header: {    ID:2,items: [{      ID:3,description:'modified child of child entity'    },{      ID:5,description:'new child of child entity'    }]  }]}

Depending on existing data, child entities will be created, updated, or deleted as follows:

• entries existing on the database, but not in the payload, are deleted → for example,ID:4
• entries existing on the database, and in the payload are updated → for example,ID:3
• entries not existing on the database are created → for example,ID:5

PUT vsPATCH — Omitted fields get reset todefault values ornull in case ofPUT requests; they are left untouched forPATCH requests.

Omitted compositions have no effect, whether duringPATCH or duringPUT. That is, to delete all children, the payload must specifynull or[], respectively, for the to-one or to-many composition.

DeepDELETE​

Deleting a root of a composition hierarchy results in a cascaded delete of all nested children.

DELETE .../Orders/1  -- would also delete all headers and items

Limitations​

Note that deepWRITE operations are only supported out of the box if the following conditions are met:

1. The on-condition of the composition only uses comparison predicates with an= operator.
2. The predicates are only connected with the logical operatorAND.
3. The operands are references or$self. CAP Java also supports pseudo variables like$user.locale.

entity Orders {  keyID : UUID;  title  : String;  Items  : Composition of manyOrderItems on substring(title, 0, 1)<= 'F' or Items.pos > 12;  Items  : Composition of manyOrderItems on Items.order = $self;}entity OrderItems {  keyorder : Association toOrders;  keypos  : Integer;  descr: String;}

Auto-Generated Keys​

OnCREATE operations,key elements of typeUUID are filled in automatically. In addition, on deep inserts and upserts, respective foreign keys of newly created nested objects are filled in accordingly.

For example, given a model like that:

entity Orders {  keyID : UUID;  title  : String;  Items  : Composition of manyOrderItems on Items.order = $self;}entity OrderItems {  keyorder : Association toOrders;  keypos  : Integer;  descr: String;}

When creating a newOrder with nestedOrderItems like that:

POST .../Orders {  title:'Order #1',Items: [    { pos:1, descr:'Item #1' },    { pos:2, descr:'Item #2' }  ]}

CAP runtimes will automatically fill inOrders.ID with a new uuid, as well as the nestedOrderItems.order.ID referring to the parent.

Searching Data​

CAP runtimes provide out-of-the-box support for advanced search of a given text in all textual elements of an entity including nested entities along composition hierarchies.

A typical search request looks like that:

GET .../Books?$search=Heights

That would basically search for occurrences of"Heights" in all text fields of Books, that is, intitle anddescr using database-specificcontains operations (for example, usinglike '%Heights%' in standard SQL).

The@cds.search Annotation​

By default search is limited to the elements of typeString of an entity that aren'tcalculated orvirtual. Yet, sometimes you may want to deviate from this default and specify a different set of searchable elements, or to extend the search to associated entities. Use the@cds.search annotation to do so. The general usage is:

@cds.search: {    element1,// included    element2 : true,// included    element3 : false,// excluded    assoc1,// extend to searchable elements in target entity    assoc2.elementA   // extend to a specific element in target entity}entity E { }

Learn more about the syntax of annotations.

Including Fields​

@cds.search: {title }entity Books { ... }

Searches thetitle element only.

Extend Search toAssociated Entities​

@cds.search: {author }entity Books { ... }@cds.search: {biography: false }entity Authors { ... }

Searches all elements of theBooks entity, as well as all searchable elements of the associatedAuthors entity. Which elements of the associated entity are searchable is determined by the@cds.search annotation on the associated entity. So, fromAuthors, all elements of typeString are searched butbiography is excluded.

Extend to Individual Elements in Associated Entities​

@cds.search: {author.name }entity Books { ... }

Searches only in the elementname of the associatedAuthors entity.

Excluding Fields​

@cds.search: {isbn: false }entity Books { ... }

Searches all elements of typeString excluding the elementisbn, which leaves thetitle anddescr elements to be searched.

Fuzzy Search on SAP HANA Cloudbeta​

Prerequisite: For CAP Java, you need to run inHEX optimization mode on SAP HANA Cloud and enablecds.sql.hana.search.fuzzy

Fuzzy search is a fault-tolerant search feature of SAP HANA Cloud, which returns records even if the search term contains additional characters, is missing characters, or has typographical errors.

You can configure the fuzziness in the range [0.0, 1.0]. The value 1.0 enforces exact search.

• Java:cds.sql.hana.search.fuzzinessThreshold
• Node.js:cds.hana.fuzzy⁽¹⁾

⁽¹⁾ If set tofalse, fuzzy search is disabled and falls back to a case insensitive substring search.

Override the fuzziness for elements, using the@Search.fuzzinessThreshold annotation:

entity Books {   @Search.fuzzinessThreshold: 0.7   title : String;}

The relevance of a search match depends on the weight of the element causing the match. By default, allsearchable elements have equal weight. To adjust the weight of an element, use the@Search.ranking annotation. Allowed values are HIGH, MEDIUM (default), and LOW:

entity Books {   @Search.ranking:HIGH   title         : String;   @Search.ranking:LOW   publisherName : String;}

Pagination & Sorting​

Implicit Pagination​

By default, the generic handlers for READ requests automaticallytruncate result sets to a size of 1,000 records max. If there are more entries available, a link is added to the response allowing clients to fetch the next page of records.

The OData response body for truncated result sets contains anextLink as follows:

GET .../Books>{  value: [    {... first record ...},    {... second record ...},    ...  ],  @odata.nextLink:"Books?$skiptoken=1000"}

To retrieve the next page of records from the server, the client would use thisnextLink in a follow-up request, like so:

GET .../Books?$skiptoken=1000

On firing this query, you get the second set of 1,000 records with a link to the next page, and so on, until the last page is returned, with the response not containing anextLink.

Reliable Pagination​

Note: This feature is available only for OData V4 endpoints.

Using a numeric skip token based on the values of$skip and$top can result in duplicate or missing rows if the entity set is modified between the calls.Reliable Pagination avoids this inconsistency by generating a skip token based on the values of the last row of a page.

The reliable pagination is available with following limitations:

• Results of functions or arithmetic expressions can't be used in the$orderby option (explicit ordering).
• The elements used in the$orderby of the request must be of simple type.
• All elements used in$orderby must also be included in the$select option, if it's set.
• Complexconcatenations of result sets aren't supported.

The feature can be enabled with the followingconfiguration options set totrue:

• Java:cds.query.limit.reliablePaging.enabled
• Node.js:cds.query.limit.reliablePaging

Paging Limits​

You can configure default and maximum page size limits in yourproject configuration as follows:

"cds": {  "query": {    "limit": {      "default":20,//> no default      "max":100     //> default 1000    }  }}

• Themaximum limit defines the maximum number of items that can get retrieved, regardless of$top.
• Thedefault limit defines the number of items that are retrieved if no$top was specified.

Annotation@cds.query.limit​

You can override the defaults by applying the@cds.query.limit annotation on the service or entity level, as follows:

@cds.query.limit: {default?,max? }| Number

The limit definitions forCatalogService andAdminService in the following example are equivalent.

@cds.query.limit.default: 20@cds.query.limit.max: 100service CatalogService {  // ...}@cds.query.limit: {default: 20,max: 100 }service AdminService {  // ...}

@cds.query.limit can be used as shorthand if no default limit needs to be specified at the same level.

@cds.query.limit: 100service CatalogService {  entity Books as projection on my.Books;//> pages at 100  @cds.query.limit: 20  entity Authors as projection on my.Authors;//> pages at 20}service AdminService {  entity Books as projection on my.Books;//> pages at 1000 (default)}

Precedence​

The closest limit applies, that means, an entity-level limit overrides that of its service, and a service-level limit overrides the global setting. The value0 disables the respective limit at the respective level.

@cds.query.limit.default: 20service CatalogService {  @cds.query.limit.max: 100  entity Books as projection on my.Books;//> default = 20 (from CatalogService), max = 100  @cds.query.limit: 0  entity Authors as projection on my.Authors;//> no default, max = 1,000 (from environment)}

Implicit Sorting​

Paging requires implied sorting, otherwise records might be skipped accidentally when reading follow-up pages. By default the entity's primary key is used as a sort criterion.

For example, given a service definition like this:

service CatalogService {  entity Books as projection on my.Books;}

The SQL query executed in response to incoming requests to Books will be enhanced with an additional order-by clause as follows:

SELECT ...from my_BooksORDER BY ID;-- default: order by the entity's primary key

If the request specifies a sort order, for example,GET .../Books?$orderby=author, both are applied as follows:

SELECT ...from my_BooksORDER BY  author,-- request-specific order has precedence  ID;-- default order still applied in addition

We can also define a default order when serving books as follows:

service CatalogService {  entity Books as projection on my.Books order by title asc;}

Now, the resulting order by clauses are as follows forGET .../Books:

SELECT ...from my_BooksORDER BY  titleasc,-- from entity definition  ID;-- default order still applied in addition

... and forGET .../Books?$orderby=author:

SELECT ...from my_BooksORDER BY  author,-- request-specific order has precedence  titleasc,-- from entity definition  ID;-- default order still applied in addition

Concurrency Control​

CAP runtimes support different ways to avoid lost-update situations as documented in the following.

Useoptimistic locking todetect concurrent modification of dataacross requests. The implementation relies onETags.

Usepessimistic locking toprotect data from concurrent modification by concurrenttransactions. CAP leverages database locks forpessimistic locking.

Conflict Detection Using ETags​

The CAP runtimes support optimistic concurrency control and caching techniques using ETags. An ETag identifies a specific version of a resource found at a URL.

Enable ETags by adding the@odata.etag annotation to an element to be used to calculate an ETag value as follows:

using {managed }from '@sap/cds/common';entity Foo : managed {...}annotate Foo with {modifiedAt @odata.etag }

The value of an ETag element should uniquely change with each update per row. ThemodifiedAt element from thepre-definedmanaged aspect is a good candidate, as this is automatically updated. You could also use update counters or UUIDs, which are recalculated on each update.

You use ETags when updating, deleting, or invoking the action bound to an entity by using the ETag value in anIf-Match orIf-None-Match header. The following examples represent typical requests and responses:

POST Employees { ID:111, name:'Name' }> 201 Created {'@odata.etag':'W/"2000-01-01T01:10:10.100Z"',...}//> Got new ETag to be used for subsequent requests...

GET Employees/111If-None-Match: "2000-01-01T01:10:10.100Z"> 304 Not Modified // Record was not changed

GET Employees/111If-Match: "2000-01-01T01:10:10.100Z"> 412 Precondition Failed // Record was changed by another user

UPDATE Employees/111If-Match: "2000-01-01T01:10:10.100Z"> 200 Ok {'@odata.etag':'W/"2000-02-02T02:20:20.200Z"',...}//> Got new ETag to be used for subsequent requests...

UPDATE Employees/111If-Match: "2000-02-02T02:20:20.200Z"> 412 Precondition Failed // Record was modified by another user

DELETE Employees/111If-Match: "2000-02-02T02:20:20.200Z"> 412 Precondition Failed // Record was modified by another user

If the ETag validation detects a conflict, the request typically needs to be retried by the client. Hence, optimistic concurrency should be used if conflicts occur rarely.

Pessimistic Locking​

Pessimistic locking allows you to lock the selected records so that other transactions are blocked from changing the records in any way.

Useexclusive locks when reading entity data with theintention to update it in the same transaction and you want to prevent the data to be locked or updated in a concurrent transaction.

Useshared locks if you only need to prevent the entity data to be locked exclusively by an update in a concurrent transaction or by a read operation with lock modeexclusive. Non-locking read operations or read operations with lock modeshared are not prevented.

The records are locked until the end of the transaction by commit or rollback statement.

Here's an overview table:

Learn more about using theSELECT ... FOR UPDATE statement in the Node.js runtime.

Learn more about using theSelect.lock() method in the Java runtime.

Input Validation​

CAP runtimes automatically validate user input, controlled by the following annotations.

@readonly​

Elements annotated with@readonly, as well ascalculated elements, are protected against write operations. That is, if a CREATE or UPDATE operation specifies values for such fields, these values aresilently ignored.

By defaultvirtual elements are alsocalculated.

@mandatory​

Elements marked with@mandatory are checked for nonempty input:null and (trimmed) empty strings are rejected.

service Sue {  entity Books {    keyID : UUID;    title  : String@mandatory;  }}

In addition to server-side input validation as introduced above, this adds a corresponding@FieldControl annotation to the EDMX so that OData / Fiori clients would enforce a valid entry, thereby avoiding unnecessary request roundtrips:

<Annotations Target="Sue.Books/title">  <Annotation Term="Common.FieldControl" EnumMember="Common.FieldControlType/Mandatory"/></Annotations>

@assert .format​

Allows you to specify a regular expression string (in ECMA 262 format in CAP Node.js and java.util.regex.Pattern format in CAP Java) that all string input must match.

entity Foo {  bar : String@assert.format: '[a-z]ear';}

@assert .range​

Allows you to specify[ min, max ] ranges for elements with ordinal types — that is, numeric or date/time types. Forenum elements,true can be specified to restrict all input to the defined enum values.

entity Foo {  bar : Integer@assert.range: [ 0, 3 ];  boo : Decimal@assert.range: [ 2.1, 10.25 ];  car : DateTime@assert.range: ['2018-10-31','2019-01-15'];  zoo : String@assert.range enum {high;medium;low; };}

... with open intervals​

By default, specified[min,max] ranges are interpreted as closed intervals, that means, the performed checks aremin ≤ input ≤ max. You can also specify open intervals by wrapping themin and/ormax values into parenthesis like that:

@assert.range: [(0),100]// 0 < input ≤ 100@assert.range: [0,(100)]// 0 ≤ input < 100@assert.range: [(0),(100)]// 0 < input < 100

In addition, you can use an underscore_ to representInfinity like that:

@assert.range: [(0),_]// positive numbers only, _ means +Infinity here@assert.range: [_,(0)]// negative number only, _ means -Infinity here

Basically values wrapped in parentheses(x) can be read asexcludingx formin ormax. Note that the underscore_ doesn't have to be wrapped into parenthesis, as by definition no number can be equal toInfinity .

Support for open intervals and infinity is available for CAP Node.js since@sap/cds version8.5 and in CAP Java since version3.5.0.

@assert .target​

Annotate amanaged to-one association of a CDS model entity definition with the@assert.target annotation to check whether the target entity referenced by the association (the reference's target) exists. In other words, use this annotation to check whether a non-null foreign key input in a table has a corresponding primary key in the associated/referenced target table.

You can check whether multiple targets exist in the same transaction. For example, in theBooks entity, you could annotate one or more managed to-one associations with the@assert.target annotation. However, it is assumed that dependent values were inserted before the current transaction. For example, in a deep create scenario, when creating a book, checking whether an associated author exists that was created as part of the same deep create transaction isn't supported, in this case, you will get an error.

The@assert.target check constraint is meant tovalidate user input and not to ensure referential integrity. Therefore onlyCREATE, andUPDATE events are supported (DELETE events are not supported). To ensure that every non-null foreign key in a table has a corresponding primary key in the associated/referenced target table (ensure referential integrity), the@assert.integrity constraint must be used instead.

If the reference's target doesn't exist, an HTTP response (error message) is provided to HTTP client applications and logged to stdout in debug mode. The HTTP response body's content adheres to the standard OData specification for an errorresponse body.

Example​

Add@assert.target annotation to the service definition as previously mentioned:

entity Books {  keyID : UUID;  title  : String;  author : Association toAuthors @assert.target;}entity Authors {  keyID : UUID;  name   : String;  books  : Association to manyBooks on books.author = $self;}

HTTP Request —assume that an author with the ID"796e274a-c3de-4584-9de2-3ffd7d42d646" doesn't exist in the database

POST BooksHTTP/1.1Accept: application/json;odata.metadata=minimalPrefer: return=minimalContent-Type: application/json;charset=UTF-8{"author_ID":"796e274a-c3de-4584-9de2-3ffd7d42d646"}

HTTP Response

HTTP/1.1 400 Bad Requestodata-version: 4.0content-type: application/json;odata.metadata=minimal{"error": {  "@Common.numericSeverity":4,  "code":"400",  "message":"Value doesn't exist",  "target":"author_ID"}}

Database Constraints​

Next to input validation, you can adddatabase constraints to prevent invalid data from being persisted.

Custom Logic​

As most standard tasks and use cases are covered bygeneric service providers, the need to add service implementation code is greatly reduced and minified, and hence the quantity of individual boilerplate coding.

The remaining cases that need custom handlers, reduce to real custom logic, specific to your domain and application, such as:

• Domain-specific programmaticValidations
• Augmenting result sets, for example to add computed fields for frontends
• ProgrammaticAuthorization Enforcements
• Triggering follow-up actions, for example calling other services or emitting outbound events in response to inbound events
• And more... In general, all the things not (yet) covered by generic handlers

In Node.js, the easiest way to add custom implementations for services is through equally named.js files placed next to a service definition's.cds file:

./srv  - cat-service.cds  # service definitions  - cat-service.js   # service implementation...

Learn more about providing service implementations in Node.js.

In Java, you'd assignEventHandler classes using dependency injection as follows:

@Component@ServiceName("org.acme.Foo")public class FooServiceImpl implements EventHandler {...}

Learn more about Event Handler classes in Java.

Custom Event Handlers​

Within your custom implementations, you can register event handlers like that:

module.exports = function (){  this.on ('submitOrder', (req)=>{...})//> custom actions  this.on ('CREATE',`Books`, (req)=>{...})  this.before ('UPDATE',`*`, (req)=>{...})  this.after ('READ',`Books`, (books)=>{...})}

@Component@ServiceName("BookshopService")public class BookshopServiceImpl implements EventHandler {  @On(event="submitOrder")public void onSubmitOrder (EventContextreq) {...}  @On(event="CREATE",entity="Books")public void onCreateBooks (EventContextreq) {...}  @Before(event="UPDATE",entity="*")public void onUpdate (EventContextreq) {...}  @After(event="READ",entity="Books")public void onReadBooks (EventContextreq) {...}}

Learn more aboutadding event handlers in Node.js.

Learn more aboutadding event handlers in Java.

Hooks:on,before,after​

In essence, event handlers are functions/method registered to be called when a certain event occurs, with the event being a custom operation, likesubmitOrder, or a CRUD operation on a certain entity, likeREAD Books; in general following this scheme:

• <hook:on|before|after> ,<event> ,[<entity>] → handler function

CAP allows to plug in event handlers to these different hooks, that is phases during processing a certain event:

• on handlers runinstead of the generic/default handlers.
• before handlers runbefore theon handlers
• after handlers runafter theon handlers, and get the result set as input

on handlers form aninterceptor stack: the topmost handler getting called by the framework. The implementation of this handler is in control whether to delegate to default handlers down the stack or not.

before andafter handlers arelisteners: all registered listeners are invoked in parallel. If one vetoes / throws an error the request fails.

Within Event Handlers​

Event handlers all get a uniformRequest/Event Message context object as their primary argument, which, among others, provides access to the following information:

• Theevent name — that is, a CRUD method name, or a custom-defined one
• Thetarget entity, if any
• Thequery inCQN format, for CRUD requests
• Thedata payload
• Theuser, if identified/authenticated
• Thetenant using your SaaS application, if enabled

Learn more aboutimplementing event handlers in Node.js.Learn more aboutimplementing event handlers in Java.

Actions & Functions​

In addition to common CRUD operations, you can declare domain-specific custom operations as shown below. These custom operations always need custom implementations in corresponding events handlers.

You can define actions and functions in CDS models like that:

service Sue {  // unbound actions & functions  function sum (x:Integer, y:Integer)returns Integer;  function stock (id: Foo:ID)returns Integer;  action add (x:Integer, to: Integer)returns Integer;  // bound actions & functions  entity Foo {keyID:Integer}actions {    function getStock()returns Integer;    action order (x:Integer)returns Integer;    //bound to the collection and not a specific instance of Foo    action customCreate (in: many $self, x: String)returns Foo;    // All parameters are optional by default, unless marked with `not null`:    action discard (reason: String not null);  }}

Learn more about modeling actions and functions in CDS.

The differentiation betweenActions andFunctions as well asbound andunbound stems from the OData specifications, and in essence is as follows:

• Actions modify data in the server
• Functions retrieve data
• Unbound actions/functions are like plain unbound functions in JavaScript.
• Bound actions/functions always receive the bound entity's primary key as implicit first argument, similar tothis pointers in Java or JavaScript. The exception are bound actions to collections, which are bound against the collection and not a specific instance of the entity. An example use case are custom create actions for the SAP Fiori elements UI.

Implementing Actions / Functions​

In general, implement actions or functions like that:

module.exports = function Sue(){  this.on('sum', ({data:{x,y}})=> x+y)  this.on('add', ({data:{x,to}})=> stocks[to]+= x)  this.on('stock', ({data:{id}})=> stocks[id])  this.on('getStock','Foo', ({params:[id]})=> stocks[id])  this.on('order','Foo', ({params:[id],data:{x}})=> stocks[id]-= x)}

Event handlers for actions or functions are very similar to those for CRUD events, with the name of the action/function replacing the name of the CRUD operations. No entity is specific for unbound actions/functions.

Method-style Implementations in Node.js, you can alternatively implement actions and functions using conventional JavaScript methods with subclasses ofcds.Service:

module.exports = class Sue extends cds.Service {  sum(x,y) {return x+y }  add(x,to) {return stocks[to]+= x }  stock(id) {return stocks[id] }  getStock(Foo,id) {return stocks[id] }  order(Foo,id,x) {return stocks[id]-= x }}

Calling Actions / Functions​

HTTP Requests to call the actions/function declared above look like that:

GET .../sue/sum(x=1,y=2)// unbound functionGET .../sue/stock(id=2)// unbound functionPOST .../sue/add {"x":11,"to":2}// unbound actionGET .../sue/Foo(2)/Sue.getStock()// bound functionPOST .../sue/Foo(2)/Sue.order {"x":3}// bound action

Note: You always need to add the() for functions, even if no arguments are required. The OData standard specifies that bound actions/functions need to be prefixed with the service's name. In the previous example, entityFoo has a bound actionorder. That action must be called via/Foo(2)/Sue.order instead of simply/Foo(2)/order. For convenience, the CAP Node.js runtime also allows the following:

• Call bound actions/functions without prefixing them with the service name.
• Omit the() if no parameter is required.
• Use query options to provide function parameters likesue/sum?x=1&y=2

Programmatic usage viageneric APIs for Node.js:

For unbound actions and functions:

async function srv.send (  event   : string | {event,data?,headers?: object },  data?   : object | any)return : resultof this.dispatch(req)

For bound actions and functions:

async function srv.send ( event   : string | {event,entity,data?,params?: array of object,headers?: object }, entity  : string, data?   : object | any)return : resultof this.dispatch(req)

• event is a name of a custom action or function
• entity is a name of an entity
• params are keys of the entity instance

Programmatic usage would look like this for Node.js:

  const srv = await cds.connect.to('Sue')  // unbound actions/functions  await srv.send('sum',{x:1,y:2})  await srv.send('stock',{id:2})  await srv.send('add',{x:11,to:2})  // actions/functions bound to collection  await srv.send('getStock','Foo',{id:2})  // for actions/functions bound to entity instance, use this syntax  await srv.send({ event:'order', entity:'Foo', data: {x:3}, params: [{id:2}]})

Note: Always pass the target entity name as second argument for bound actions/functions.

Programmatic usage viatyped API — Node.js automatically equips generated service instances with specific methods matching the definitions of actions/functions found in the services' model. This allows convenient usage like that:

  const srv = await cds.connect.to(Sue)  // unbound actions/functions  srv.sum(1,2)  srv.stock(2)  srv.add(11,2)  // bound actions/functions  srv.getStock('Foo',2)  srv.order('Foo',2,3)

Note: Even with that typed APIs, always pass the target entity name as second argument for bound actions/functions.

Serving Media Data​

CAP provides out-of-the-box support for serving media and other binary data.

Annotating Media Elements​

You can use the following annotations in the service model to indicate that an element in an entity contains media data.

@Core.MediaType : Indicates that the element contains media data (directly or using a redirect). The value of this annotation is either a string with the contained MIME type (as shown in the first example), or is a path to the element that contains the MIME type (as shown in the second example).

@Core.IsMediaType : Indicates that the element contains a MIME type. The@Core.MediaType annotation of another element can reference this element.

@Core.IsURL @Core.MediaType : Indicates that the element contains a URL pointing to the media data (redirect scenario).

@Core.ContentDisposition.Filename : Indicates that the element is expected to be displayed as an attachment, that is downloaded and saved locally. The value of this annotation is a path to the element that contains the Filename (as shown in the fourth example ).

@Core.ContentDisposition.Type : Can be used to instruct the browser to display the element inline, even if@Core.ContentDisposition.Filename is specified, by setting toinline (see the fifth example). If omitted, the behavior is@Core.ContentDisposition.Type: 'attachment'.

Learn more how to enable stream support in SAP Fiori elements.

The following examples show these annotations in action:

1. Media data is stored in a database with a fixed media typeimage/png:

entity Books {//...  image : LargeBinary@Core.MediaType: 'image/png';}

2. Media data is stored in a database with avariable media type:

entity Books {//...  image : LargeBinary@Core.MediaType:imageType;  imageType : String@Core.IsMediaType;}

3. Media data is stored in an external repository:

entity Books {//...  imageUrl  : String@Core.IsURL @Core.MediaType:imageType;  imageType : String@Core.IsMediaType;}

4. Content disposition data is stored in a database with avariable disposition:

entity Authors {//...  image : LargeBinary@Core.MediaType:imageType @Core.ContentDisposition.Filename:fileName;  fileName : String;}

5. The image shall have the suggested file name but be displayed inline nevertheless:

entity Authors {//...  image : LargeBinary@Core.MediaType:imageType @Core.ContentDisposition.Filename:fileName @Core.ContentDisposition.Type: 'inline';  fileName : String;}

Learn more about the syntax of annotations.

Reading Media Resources​

Read media data usingGET requests of the form/Entity(<ID>)/mediaProperty:

GET ../Books(201)/image> Content-Type: application/octet-stream

The response'sContent-Type header is typicallyapplication/octet-stream.

Although allowed byRFC 2231, Node.js does not support line breaks in HTTP headers. Hence, make sure you remove any line breaks from your@Core.IsMediaType content.

Read media data with@Core.ContentDisposition.Filename in the model:

GET ../Authors(201)/image> Content-Disposition: 'attachment; filename="foo.jpg"'

The media data is streamed automatically.

Learn more about returning a custom streaming object (Node.js - beta).

Creating a Media Resource​

As a first step, create an entity without media data using a POST request to the entity. After creating the entity, you can insert a media property using the PUT method. The MIME type is passed in theContent-Type header. Here are some sample requests:

POST ../BooksContent-Type: application/json{<JSON> }

PUT ../Books(201)/imageContent-Type: image/png<MEDIA>

The media data is streamed automatically.

Updating Media Resources​

The media data for an entity can be updated using the PUT method:

PUT ../Books(201)/imageContent-Type: image/png<MEDIA>

The media data is streamed automatically.

Deleting Media Resources​

One option is to delete the complete entity, including all media data:

DELETE ../Books(201)

Alternatively, you can delete a media data element individually:

DELETE ../Books(201)/image

Using External Resources​

The following are requests and responses for the entity containing redirected media data from the third example, "Media data is stored in an external repository".

This format is used by OData-Version: 4.0. To be changed in OData-Version: 4.01.

GET: ../Books(201)>{ ...    image@odata.mediaReadLink:"http://other-server/image.jpeg",    image@odata.mediaContentType:"image/jpeg",    imageType: "image/jpeg"}

Conventions & Limitations​

General Conventions​

• Binary data in payloads must be a Base64 encoded string.
• Binary data in URLs must have the formatbinary'<url-safe base64 encoded>'. For example:

GET $filter=ID eq binary'Q0FQIE5vZGUuanM='

Node.js Runtime Conventions and Limitations​

• The usage of binary data in some advanced constructs like the$apply query option and/any() might be limited.
• On SQLite, binary strings are stored as plain strings, whereas a buffer is stored as binary data. As a result, if in a CDS query, a binary string is used to query data stored as binary, this wouldn't work.
• Please note, that SQLite doesn't support streaming. That means, that LargeBinary fields are read as a whole (not in chunks) and stored in memory, which can impact performance.
• SAP HANA Database Client for Node.js (HDB) and SAP HANA Client for Node.js (@sap/hana-client) packages handle binary data differently. For example, HDB automatically converts binary strings into binary data, whereas SAP HANA Client doesn't.
• In the Node.js Runtime, all binary strings are converted into binary data according to SAP HANA property types. To disable this default behavior, you can set the environment variablecds.hana.base64_to_buffer: false.

Best Practices​

Single-Purposed Services​

We strongly recommend designing your services for single use cases. Services in CAP are cheap, so there's no need to save on them.

DON'T: Single Services Exposing All Entities 1:1​

The anti-pattern to that are single services exposing all underlying entities in your app in a 1:1 fashion. While that may save you some thoughts in the beginning, it's likely that it will result in lots of headaches in the long run:

• They open huge entry doors to your clients with only few restrictions
• Individual use-cases aren't reflected in your API design
• You have to add numerous checks on a per-request basis...
• Which have to reflect on the actual use cases in complex and expensive evaluations

DO: One Service Per Use Case​

For example, let's assume that we have a domain model definingBooks andAuthors more or less as above, and then we addOrders. We could define the following services:

using {my.domain as my }from './db/schema';

/** Serves end users browsing books and place orders */service CatalogService {  @readonly entity Books as select from my.Books {    ID,title,author.name as author  };  @requires: 'authenticated-user'  @insertonly entity Orders as projection on my.Orders;}

/** Serves registered users managing their account and their orders */@requires: 'authenticated-user'service UsersService {  @restrict: [{grant: 'READ',where: 'buyer = $user' }]// limit to own ones  @readonly entity Orders as projection on my.Orders;  action cancelOrder ( ID:Orders.ID, reason:String );}

/** Serves administrators managing everything */@requires: 'authenticated-user'service AdminService {  entity Books   as projection on my.Books;  entity Authors as projection on my.Authors;  entity Orders  as projection on my.Orders;}

These services serve different use cases and are tailored for each. Note, for example, that we intentionally don't expose theAuthors entity to end users.

Late-Cut Microservices​

Compared to Microservices, CAP services are 'Nano'. As shown in the previous sections, you should design your application as a set of loosely coupled, single-purposed services, which can all be served embedded in a single-server process at first (that is, a monolith).

Yet, given such loosely coupled services, and enabled by CAP's uniform way to define and consume services, you can decide later on to separate, deploy, and run your services as separate microservices, even without changing your models or code.

This flexibility allows you to, again, focus on solving your domain problem first, and avoid the efforts and costs of premature microservice design and DevOps overhead, at least in the early phases of development.