Providing Services

In this lesson, we will limit ourselves to the creation of service definitions and the OData V4 protocol adapter that automatically serves all CRUD operations for the exposed entities. Later we will also discuss how to implement custom domain logic.

Let's now take a look at how to write a service definition with CDS (CDS Definition Language) and CQL (CDS Query Language). To do this, we create a file with the extension .cds in the srv folder of the CAP project. The name of the file is arbitrary, in our example we use admin-service.cds as the name (see figure A Simple Service Definition).

In line 1 of the service definition, the using directive is employed to import the definitions from the domain model. The specified from path starting with ../ is resolved relative to the srv folder in which the service definition is located. This imports all definitions with the namespace prefix com.sap.learning from the db/schema.cds file. The local alias db is set for the imported definitions.

Lines 4 to 9 contain a service block that defines a service interface called AdminService as a collection of exposed entities. This service is intended for administrators to manage authors and books within an application.

By default, the endpoint of an exposed service is constructed based on its name, following some conventions (the string 'Service' is omitted and kebab-case is enforced). If you want to override the default path or make it explicit, you can add the @path annotation as in the example. There, the @path annotation specifies the URL path under which this service will be accessible, namely /admin.

The entities exposed by a service are usually projections on entities from the underlying data model. Standard view definitions, using as select from or as projection on, can be used for exposing entities.

Two entities are defined as projections within the AdminService:

• Line 6 declares an entity called Books within the AdminService. This is a projection, i.e. it is a view on the Books entity defined in the imported domain model.
• Similarly, in line 7, an Authors entity is declared as a projection on the Authors entity from the domain model.

The service definition in the example shown allows access to the underlying data in a 1:1 manner.

When cds watch is executed, SQL DDL statements are generated based on the service model and executed in the configured database. These SQL DDL statements can also be created manually using the cds compile command already discussed in connection with the domain model.

To display the SQL DDL statements generated for the example discussed here, execute the following command in the root directory of the CAP project in the terminal:

1
cds compile srv/admin-service.cds --to sql

The generated SQL DDL script contains the CREATE TABLE statements already discussed above for the com_sap_learning_Authors and com_sap_learning_Books tables. They belong to the entities from the domain model. In addition, the CREATE VIEW statements shown in figure Generated Views are now also generated. This means that the two projected entities Authors and Books from the service model are created as views in the database. The views read their data from the generated model tables.

The AdminService served in the example is a fully implemented OData V4 service - served by CAP's generic runtimes, without any implementation coding required.

If you send a GET request to the root URL of the service, you will receive the service document back, which lists the resources offered by the service (see figure Service Document).

The service discussed here contains - based on the service model - the two entity sets Authors and Books. They are associated with the two service endpoints /admin/Authors and /admin/Books. All OData CRUD operations are supported out-of-the-box via these two endpoints. When creating new Authors or Books entities, the respective ID key field is filled automatically, as the key fields have been typed with UUID.

Watch the video to see how to define a service.