Defining services and using generic providers

A service is the API your app offers. In CAP, services usually expose projections on domain entities: views that select, rename or exclude elements for one use case. The domain model stays stable while each service shows exactly what its consumers need. This lesson defines the fleet app's services and shows how much CAP serves before you write any code.

Service definitions

The fleet desk's service goes in srv/fleet-service.cds:
using { com.contoso.fleet as my } from '../db/schema';
service FleetService @(path: '/fleet') {
entity Inquiries as projection on my.Inquiries;
@readonly entity Topics as projection on my.Topics;
action closeInquiry (ID : UUID, resolution : String);
}
A second service, AdminService, exposes Topics for maintenance by the fleet desk supervisor. @readonly on Topics in FleetService means agents can read the code list but not change it there.

Actions and functions add operations beyond create, read, update and delete. Use an action for something that changes state (closing an inquiry, with a resolution text) and a function for a read-only computation. Actions make intent explicit: rather than letting any client set status = 'Closed' by a generic update, the service offers closeInquiry, whose handler can check that a resolution is given and that the user may close inquiries.

What the generic providers serve

Declarative validation first

CAP's documentation recommends declaring input checks in the model rather than coding them. @mandatory rejects missing or empty input. @assert.range checks numbers, dates or enumerations (priority must be 1 to 3). @assert.format checks a string against a regular expression, and @assert.target on a managed to-one association checks that the referenced record exists, so an inquiry cannot point to a topic code that is not in the list. Each annotation can carry a custom message. Declarative checks are visible in the model, consistent across services, and need no handler code.

Projections can do more than pass entities through. A projection can exclude elements a consumer should not see, rename elements to the consumer's vocabulary, or add a where clause so that, for example, a service for fleet customers only ever exposes inquiries that are not marked internal. Because the restriction is part of the service definition, it applies to every request, and a test can prove it once for the whole API instead of screen by screen. Keep in mind that a projection's filter is a modeling choice, not an authorization rule; user-specific restrictions belong in the authorization annotations covered in course sap-btp-204.