SAP CAP Tutorial: Enforcing REST at Enterprise Scale

@Before(event = CqnService.EVENT_CREATE, entity = User _. CDS_NAME)
public void beforeCreate(User user) {
String email = user.getEmail();
if (email == null || !email.contains("@")) {
throw new IllegalArgumentException("Invalid email address.");
}
}

When you put everything together, a single CDS entity and a single CDS service effectively replace a large amount of traditional infrastructure: controllers, repositories, DTOs, mappers, validation layers, error handling, batching, and even parts of API documentation.

With minimal setup, a CAP service built from one CDS entity and one CDS service already provides a production-ready API out of the box. From day one, it supports:

• PATCH/PUT/POST/DELETE semantics out of the box (+ $batch)
• Filtering ($filter), sorting ($orderby), pagination ($top, $skip, $count)
• Expansions & joins ($expand), field projection ($select)
• Search/text filters
• Server‑driven paging ($skiptoken)
• AuthZ rules (role checks via @requires, capability annotations)
• AuthN integration (XSUAA / BTP; local dev auth)
• Machine‑readable service metadata ($metadata EDMX)
• OpenAPI spec generation from CDS (for non‑OData consumers)
• Best practices: optimistic locking, ETag, concurrency control
• Development features: basic authentication, SQLite/H2

If you are already developing with this framework, you get access to a mature tooling ecosystem. CAP provides plugins for IntelliJ IDEA and VS Code, CDS Maven and CDS Lint (ESLint plugin), and comprehensive official guides and SAP CAP best practices from SAP. In addition, CAP is well supported by modern LLMs, which makes it easy to accelerate SAP CAP development using tools like ChatGPT or SAP AI services .

Here is an example of how quickly a production-ready API can be built and extended using CAP and OData.

How to Build REST APIs with SAP CAP and OData?

Let’s create a new SAP CAP project using IntelliJ IDEA. First, we create an empty project and initialize it via the terminal. For that, the SAP CDS SDK must be installed. Once installed, we run the CDS initialization command with the Java flag, so the project is generated as a Java-based CAP application rather than Node.js.

After initialization, the project structure is created automatically. The result is a Maven-based, Spring Boot–powered application, which we can easily import as a Maven project to simplify further work.

Next, we create the database schema. This is done by creating a CDS file schema.cds in the db package.

In our example, the schema contains two entities: Department and Employee, linked by an association.

We define a namespace, specify primary keys, and add basic fields such as names and email. The syntax is straightforward and familiar to anyone with SQL experience.

Once the schema is ready, we need to expose it through a service. For that, we create a CDS service definition employee-service.cds in the srv package. The service imports the database schema and exposes projections for the entities we want to make available via the API.

At this point, we already have everything needed to start the application. We build the project using Maven, which generates the necessary Java classes and prepares the Spring Boot application. After that, we run the application and verify that it starts successfully.

mvn clean install
mvn spring-boot:run

A simple request to the service confirms that the API is running, even though the database is still empty.

We can also inspect the service metadata by calling the $metadata endpoint.  

This metadata describes the full service contract and is all a client needs to understand how to interact with the API. At this stage, the application is already stable and usable.

Let's add some testing data.

First, we stop the application. To add this data, you need to run another CDS query.

cds add data

This creates a new database package containing two empty CSV files, which we’ll populate with data.

Instead of filling them manually, we use an AI-assisted approach inside IntelliJ to generate sample data based on the CDS schema.

I recommend Claude here because it's probably the best with CAP framework, but ChartGPT4 is good enough too. And I will use a prompt, which is asking for the generation of CSV data based on this schema, and restricting Cloud not to create something not compatible with our system. Nothing special. Here are the test data generated:

ID,name
a1b2c3d4-e5f6-7890-abcd-ef1234567890,Human Resources
b2c3d4e5-f6g7-8901-bcde-f23456789012,Engineering
c3d4e5f6-g7h8-9012-cdef-345678901234,Marketing
d4e5f6g7-h8i9-0123-defa-456789012345,Finance
e5f6g7h8-i9j0-1234-efab-567890123456,Operations

ID,name,email,department_ID

f6g7h8i9-j0k1-2345-fabc-678901234567,John Smith,john.smith@example.com,b2c3d4e5-f6g7-8901-bcde-f23456789012
g7h8i9j0-k1l2-3456-gbcd-789012345678,Sarah Johnson,sarah.johnson@example.com,a1b2c3d4-e5f6-7890-abcd-ef1234567890
h8i9j0k1-l2m3-4567-hcde-890123456789,Michael Davis,michael.davis@example.com,b2c3d4e5-f6g7-8901-bcde-f23456789012
i9j0k1l2-m3n4-5678-idef-901234567890,Emily Wilson,emily.wilson@example.com,c3d4e5f6-g7h8-9012-cdef-345678901234
j0k1l2m3-n4o5-6789-jefa-012345678901,David Brown,david.brown@example.com,d4e5f6g7-h8i9-0123-defa-456789012345
k1l2m3n4-o5p6-7890-kfab-123456789012,Lisa Anderson,lisa.anderson@example.com,a1b2c3d4-e5f6-7890-abcd-ef1234567890
l2m3n4o5-p6q7-8901-lgbc-234567890123,Robert Taylor,robert.taylor@example.com,e5f6g7h8-i9j0-1234-efab-567890123456
m3n4o5p6-q7r8-9012-mhcd-345678901234,Jennifer Garcia,jennifer.garcia@example.com,c3d4e5f6-g7h8-9012-cdef-345678901234
n4o5p6q7-r8s9-0123-nide-456789012345,Christopher Miller,christopher.miller@example.com,b2c3d4e5-f6g7-8901-bcde-f23456789012
o5p6q7r8-s9t0-1234-ojef-567890123456,Amanda Martinez,amanda.martinez@example.com,d4e5f6g7-h8i9-0123-defa-456789012345

The departments and employees are now generated, so we can replace the data file and restart the application. That’s all we need at this stage.

After restarting, the test data appears immediately when we query the API. If we fetch employees again, we now get the full dataset, including their associated departments.

We can expand departments directly in the same response payload by adding a simple $expand to the URL. The department data is returned inline, without any extra requests.

/odata/v4/EmployeeService/Employees?$expand=department

We can also filter by department while keeping the expansion. For example, adding a filter for department/name eq 'Engineering' returns only employees from that department. The query remains readable and intuitive.

/odata/v4/EmployeeService/Employees?$filter=department/name eq 'Engineering'

The same applies to departments themselves. We can fetch all departments, or request a single one by adjusting the URL. The structure closely resembles how we navigate objects in Java, so the behavior should feel familiar to most developers.

At this point, the database and application are set up, so we can create a new employee. We send a POST request with a name and email, and the record is created successfully.

However, the email is stored without any validation. That’s a problem is that we don’t want invalid data polluting the database. CAP doesn’t enforce this validation by default, so we need to extend the application logic.

To do that, we’ll add a new handlers package. Since this is a standard boilerplate, there’s no reason to write it from scratch. I’ll ask Claude to generate it for me.

Inside the handler, we implement simple email validation logic. If the validation fails, we throw a service exception, which results in a proper error response for the client.

After restarting the application, we test the same request again. This time, invalid data is rejected, and the response clearly indicates what went wrong. With minimal effort, we’ve extended the default behavior and improved data quality without rewriting the core API.

This is how we extended the application. It now validates data more reliably, preventing incorrect input, and is ready for deployment to a real environment.

Conclusion

In short, SAP CAP gives you a lot out of the box, but it works best when you stay within its abstraction level. If your use case requires deep, low-level control, or very lightweight, non–data-centric microservices, it may feel like overkill. OData is powerful, even if it looks unusual at first, especially if you’re used to JSON-RPC or simpler REST styles.

That said, SAP isn’t going away. If you work in an enterprise environment, you will likely encounter it sooner or later. So when you see SAP CAP or OData in a project, don’t treat it as a problem. It’s just a design choice, with clear trade-offs. Once you understand those trade-offs, SAP Cloud Application Programming Model (CAP) becomes another tool you can work with confidently, not something to be afraid of.

Frequently Asked Questions

Does SAP CAP support SQLite for local development?

Yes. SAP CAP fully supports SQLite and H2 as development databases. SQLite is the default option, so you can run CAP applications locally without any additional configuration. This makes local setup fast and frictionless for developers.

What are the disadvantages of OData?

The main drawback of OData is verbosity. Compared to RPC, SOAP, simpler REST styles or GraphQL, OData payloads and URLs can be heavy. This becomes especially noticeable in event-driven architectures, streaming scenarios, or mobile applications, where bandwidth, memory usage, and CPU consumption matter.

OData is a self-describing protocol. Even if you need two fields, the response often contains metadata such as@odata.context, @odata.type, @odata.count, links (e.g., @odata.nextLink) and so on.

That increases payload size. While this is acceptable for enterprise systems, it can be inefficient for mobile or highly bandwidth-sensitive use cases. The protocol's flexibility comes at the cost of long, complex URLs that require a sophisticated client.

GraphQL vs. OData: When should we use GraphQL?

GraphQL is often a better choice when bandwidth optimization is critical (mobile clients), or clients need very fine-grained control over response shapes, or the system is event-driven or highly decoupled.

OData, on the other hand, works best for enterprise, data-centric applications where consistency, standardization, and tooling support matter more than extreme flexibility.

Are there scenarios SAP CAP does not handle well?

One of the most common pain points is the use of actions and functions with binary streams and files. For example, you might want to load a large volume of data from an Excel file using an action, or, conversely, get a CSV representation of an object from a function. Currently, this isn't directly supported.

As a result, you're left with a choice. You can either split the API into two operations by first uploading the data to the database, which requires defining an entity, and then processing it by ID. Or, take a different route and implement a custom Spring controller.

Overall, the trend is that the further away from structured data, the less convenient CAP is.

How do SAP CAP handlers work if they live in a different folder?

CAP extends the Spring Boot model. Generated code is placed in a dedicated gen folder, while custom logic (including handlers) lives alongside the main application code.

At runtime, CAP automatically resolves and wires generated interfaces with custom implementations using annotations and internal framework mechanisms. While this structure may look unusual at first, it is intentional and fully supported by the framework.

Is it acceptable to use AI for projects?

It depends on project and company policies. In most cases, using AI for: test data generation, mock data, boilerplate or scaffolding code are acceptable. However, using AI for business logic or sensitive data should be handled with caution and explicit approval.

For examples, some SAP environments already integrate AI with strict security controls, but teams should always align with their project manager and security guidelines.

Is there documentation for setting up CAP with IntelliJ IDEA and Maven?

Yes. SAP provides official documentation and guides for setting up CAP projects with IntelliJ IDEA, Maven, and Java. These resources can be shared separately and are usually sufficient to reproduce a working local environment.

Can after/before handlers be used to reduce OData verbosity?

Technically, yes, but not in terms of data structure, and they should not be used for that purpose. Overwriting responses in handlers defeats the core idea of OData, where clients explicitly define what they want via query options ($select, $expand, $filter).

If payload size is a concern, it’s better to design queries carefully rather than manipulate responses in handlers.

How does schema evolution work in SAP CAP?

To put it very simply, schema evolution is handled by the HDI container, based on the delta detected between the previous and current version of the schema in the CDS definitions (or, more precisely, in the artifacts that are generated based on them).

This topic is broad and typically requires a dedicated discussion or documentation.