Your CAP service meets the real world
Sooner or later your CAP app needs live data from elsewhere — S/4HANA business partners, a product master, a tax service. CAP's external service support makes remote APIs feel almost local.
Import the remote API's definition, and CAP generates a typed client: query it like a local entity, with promises instead of HTTP calls.
Step 1: Import the API definition
With an EDMX file from the SAP API Business Hub:
cds import ./API_BUSINESS_PARTNER.edmx --as cds
This generates srv/external/API_BUSINESS_PARTNER.csn — a CDS model of the remote service. Check it into source control; regenerate when the API changes.
Step 2: Declare it as a required service
// package.json
"cds": {
"requires": {
"API_BUSINESS_PARTNER": {
"kind": "odata",
"model": "srv/external/API_BUSINESS_PARTNER",
"[production]": {
"credentials": {
"destination": "S4HANA",
"path": "/sap/opu/odata/sap/API_BUSINESS_PARTNER"
}
}
}
}
}
Locally, mock it or point at a sandbox; in production, resolve it through a BTP destination named S4HANA. Credentials live in the destination, never in code.
Step 3: Use it in handlers
this.on('READ', 'BusinessPartners', async (req) => {
const bupa = await cds.connect.to('API_BUSINESS_PARTNER');
return bupa.run(req.query);
});
The killer line: bupa.run(req.query) forwards the incoming OData query — filters, paging, selects — to S/4HANA. Your service becomes a pass-through with zero mapping code.
Forwarding
req.queryto the remote service preserves $filter, $top, and $orderby end-to-end. Don't reimplement what the remote system already does.
Mashups: local + remote
- Enrich locally — read the remote partner, join with your local orders in an
after READhandler. - Cache reference data — replicate slow-moving remote data into local entities on a schedule.
- Handle failures — remote calls fail; wrap them with timeouts and fallbacks, and never let a slow remote system block your UI thread silently.
- Respect auth — propagate the user token (principal propagation) so S/4HANA applies its own authorizations.
Error handling and resilience
Remote calls fail — networks partition, systems go down for maintenance. Never let a remote failure surface as a cryptic 500. Wrap external calls with timeouts and translate failures into meaningful OData errors:
try {
return await bupa.run(req.query);
} catch (e) {
req.error(502, 'Business partner system unavailable, try again shortly');
}
For read-heavy mashups, cache remote reference data locally and refresh on a schedule. Your UI stays fast and survives remote outages. For writes, consider the outbox pattern: accept the request, emit an event, and let a background handler call the remote system with retries.
Your service, their data
External services turn CAP into an integration layer: one OData API for your UI, backed by whatever mix of local and remote systems the business needs.
Integrating a specific S/4HANA API? Name it in the comments.