Remote Services accept CQN statements and transform these into API calls on remote endpoints. The CAP Java SDK supports Remote Services for OData V2 and V4 APIs out of the box. To enable these capabilities in an application, add the following Maven dependency to your project:
To execute HTTP requests, CAP leverages the SAP Cloud SDK. After adding the dependency mentioned above, both libraries integrate seamlessly with each other. CAP ensures to automatically propagate tenant and user information from the Request Context to the Cloud SDK.
CAP's clear recommendation is to use Remote Services over directly leveraging the SAP Cloud SDK. The CQN query APIs enable late-cut microservices and simplified mocking capabilities. Regarding multitenant applications, these APIs keep you extensible, even towards remote APIs. In addition, they free developers from having to map CQN to OData themselves.
Remote Services use a CDS service definition from the CDS model as specification of the remote API. This API specification is required in order to properly translate CQN statements into respective OData V2 and V4 requests.
By default the CDS service definition is looked up in the CDS model using the name of the Remote Service. However, the name of the Remote Service needs to be unique, as it's also used to look up the service in Java. Therefore, it is also possible to explicitly configure the name of the CDS service definition from the CDS model using the model property. This is especially useful, when creating multiple Remote Services for the same API with different destinations:
CAP leverages the destination capabilities of the SAP Cloud SDK. Destinations contain the information necessary to connect to a remote system. They're basically an advanced URL, that can carry additional metadata like, for example, the authentication information for this URL.
The CAP Java SDK obtains the destination for a Remote Service from the DestinationAccessor using the name, that is configured in the Remote Service's destination configuration. If you're using the SAP BTP Destination Service, this is the name you used when you defined the destination there.
The destination configuration needs to provide the URL to the OData V2 or V4 service, that should be used by the Remote Service. This service URL can be built from three parts:
The URL provided by the destination.
An optional URL suffix provided in the Remote Service destination configuration under the suffix property.
The name of the service, either obtained from the optional service configuration property or the fully qualified name of the CDS service definition.
In this case, the destination with name s4-business-partner-api would be obtained from the DestinationAccessor. Given that this destination holds the URL https://s4.sap.com, the resulting service URL for OData requests would be https://s4.sap.com/sap/opu/odata/sap/API_BUSINESS_PARTNER.
The type property defines the protocol used by the remote API. The CAP Java SDK currently supports odata-v4 (default) or odata-v2.
If you don't require to use the SAP BTP Destination Service, you can also programmatically build destinations and add them to the DestinationAccessor. You can easily register an event handler that is executed during startup of the application and build custom destinations:
Note that you can leverage Spring Boot's configuration possibilities to inject credentials into the destination configuration. The same mechanism can also be used for the URL of the destination by also reading it from your application configuration (for example environment variables or application.yaml). This is especially useful when integrating micro-services, which may have different URLs in productive environments and test environments.
The CAP Java SDK only includes the minimum SAP Cloud SDK dependencies required out of the box. In case you want to leverage features from SAP Cloud SDK, like the programmatic destination registration or integration with SAP BTP Destination Service, you need to add additional dependencies.
It's recommended to add the SAP Cloud SDK BOM to the dependency management section of your application's parent POM. If you are also using the CDS Services BOM or the Spring Boot dependencies BOM, it's recommended to add the SAP Cloud SDK BOM after these:
Keep in mind, that Remote Services are simply clients to remote APIs. CAP doesn't automatically forward CQN queries to these services. Developers need to explicitly call and use these Remote Services in their code. However, as Remote Services are based on the common CQN query APIs it's easy to use them in event handlers of your Application Services.
In case data from Remote Services should be combined with data from the database custom coding is required. Refer to the Integrate and Extend guide for more details.