sapui5tutors SAPUI5 • Fiori • SAP BTP Step-by-step tutorials Real project examples Interview Q&A
Practical SAPUI5 • Fiori • SAP BTP tutorials and interview prep

CAPM External Services: Consuming S/4HANA APIs

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.query to 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 READ handler.
  • 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.