diff --git a/guides/deploy/to-cf.md b/guides/deploy/to-cf.md index b83cb6055..02bf311af 100644 --- a/guides/deploy/to-cf.md +++ b/guides/deploy/to-cf.md @@ -131,11 +131,9 @@ The roles/scopes are derived from authorization-related annotations in your CDS ### 3. Remote Service Consumption {#remote-services} -CAP supports two HTTP clients for remote service calls. +CAP supports two HTTP clients for remote service calls: [SAP Cloud SDK](../../node.js/remote-services#sap-cloud-sdk) and CAP's built-in [native fetch client](../../node.js/remote-services#native-fetch). -#### SAP Cloud SDK {#add-cloud-sdk} - -If you intend to consume remote services in production, for example, via [BTP Destinations](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/destination-service), add the requisite SAP Cloud SDK packages, like that for Node.js: +If you need full SAP BTP Destination service support including on-premise connectivity, add the SAP Cloud SDK packages: ```shell npm add @sap-cloud-sdk/connectivity @@ -145,19 +143,9 @@ npm add @sap-cloud-sdk/resilience [Learn more about consuming remote services with SAP Cloud SDK.](https://sap.github.io/cloud-sdk/docs/js/overview){.learn-more} -#### Native Fetch Client {#native-fetch} - -CAP provides a built-in remote client that uses the native Node.js `fetch` API. For limitations, see the warning below. During local development, you don't need SAP Cloud SDK, but you can still use it. For production, you still need SAP Cloud SDK. For example, you use it to resolve named destinations through the SAP BTP Destination service. - -CAP selects the native fetch client for each outgoing request according to the following rules: +Alternatively, CAP's built-in native fetch client supports SAP BTP destinations without SAP Cloud SDK. -1. If the destination requires features only available in SAP Cloud SDK (for example, SAP BTP Destination service resolution or non-basic authentication), CAP always uses SAP Cloud SDK. -2. If you explicitly set cds.remote.native_fetch to `true` or `false`, CAP uses that setting. -3. Otherwise, CAP uses native fetch when you haven't installed `@sap-cloud-sdk/http-client`. - -::: warning Current limitations -The native fetch client does not yet support named destinations using the SAP BTP Destination service. It supports only [application-defined destinations](../services/consuming-services#use-application-defined-destinations). In addition, it limits authentication to `NoAuthentication` and `BasicAuthentication`. -::: +[Learn more about the native fetch client.](../../node.js/remote-services#native-fetch){.learn-more} ### 4. MTA-Based Deployment {#add-mta-yaml} diff --git a/guides/integration/service-bindings.md b/guides/integration/service-bindings.md index 5a5c1863b..cf2d76811 100644 --- a/guides/integration/service-bindings.md +++ b/guides/integration/service-bindings.md @@ -110,5 +110,123 @@ cds env requires -b ## Destinations +Destinations provide the connectivity details needed to reach a remote system, essentially a named URL enriched with metadata such as authentication configuration. + +CAP supports named destinations from the [SAP BTP Destination service](#btp-destination-service) as well as [application-defined destinations](#application-defined-destinations) configured directly in your project. + +### SAP BTP Destination Service {#btp-destination-service} + +Named destinations are resolved from the SAP BTP Destination service. Configure the destination name in the `credentials` block of the required service: + +```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" + } + } + } + } +} +``` + +Bind the Destination service to your application: + +```sh +cds add destination +``` + +#### Native Fetch Client {#native-fetch-destinations} + +When the [native fetch client](../../node.js/remote-services#native-fetch) is active, CAP resolves SAP BTP destinations natively without SAP Cloud SDK. + +**Supported authentication types:** + +| Authentication | Supported | +|---|:---:| +| `NoAuthentication` | ✓ | +| `BasicAuthentication` | ✓ | +| `OAuth2ClientCredentials` | ✓ | + +**Configuration:** + +| Property | Default | Description | +|---|---|---| +| `timeout` | `'10s'` | Timeout for SAP BTP Destination service and token requests | + +```json +"cds": { + "remote": { + "native_fetch": true, + "timeout": "30s" + } +} +``` + +::: warning Proxy type limitation +Only destinations with proxy type `Internet` are fully supported. On-premise destinations (proxy type `OnPremise`) require SAP Cloud SDK. +::: + +#### SAP Cloud SDK + +When the native fetch client isn't active, CAP uses the SAP Cloud SDK to resolve SAP BTP destinations. Additional `destinationOptions` can be passed to control resolution behavior: + +```jsonc +"cds": { + "requires": { + "API_BUSINESS_PARTNER": { + /* ... */ + "[production]": { + "credentials": { + /* ... */ + }, + "destinationOptions": { + "selectionStrategy": "alwaysSubscriber", + "useCache": true + } + } + } + } +} +``` + +[Learn more about destinations with SAP Cloud SDK.](../services/consuming-services#use-sap-btp-destinations){.learn-more} + +### Application-Defined Destinations {#application-defined-destinations} + +If you don't want to use SAP BTP destinations, you can define the URL, authentication details, and additional metadata directly in your CAP configuration: + +```json +"cds": { + "requires": { + "REVIEWS": { + "kind": "odata", + "model": "srv/external/REVIEWS", + "[production]": { + "credentials": { + "url": "https://reviews.ondemand.com/reviews", + "authentication": "BasicAuthentication", + "username": "", + "password": "", + "headers": { + "my-header": "header value" + }, + "queries": { + "my-url-param": "url param value" + } + } + } + } + } +} +``` + +[Learn more about application-defined destinations.](../services/consuming-services#use-application-defined-destinations){.learn-more} + ## Service Keys ## Using API Keys diff --git a/guides/services/consuming-services.md b/guides/services/consuming-services.md index 30d4060b6..56a5f9eef 100644 --- a/guides/services/consuming-services.md +++ b/guides/services/consuming-services.md @@ -517,7 +517,7 @@ External service definitions, like [generated CDS or CSN files during import](#i It's best practice to use your own "interface" to the external service and define the relevant fields in a projection in your namespace. Your implementation is then independent of the remote service implementation and you request only the information that you require. ```cds -using {  API_BUSINESS_PARTNER as bupa } from '../srv/external/API_BUSINESS_PARTNER'; +using { API_BUSINESS_PARTNER as bupa } from '../srv/external/API_BUSINESS_PARTNER'; entity Suppliers as projection on bupa.A_BusinessPartner { key BusinessPartner as ID, @@ -590,7 +590,7 @@ What you need to do depends on [the scenarios](#sample-scenario-from-end-to-end- To expose a remote service entity, you add a projection on it to your CAP service: ```cds -using {  API_BUSINESS_PARTNER as bupa } from '../srv/external/API_BUSINESS_PARTNER'; +using { API_BUSINESS_PARTNER as bupa } from '../srv/external/API_BUSINESS_PARTNER'; extend service RiskService with { entity BusinessPartners as projection on bupa.A_BusinessPartner; @@ -680,7 +680,7 @@ module.exports = cds.service.impl(async function() { It's possible to expose associations of a remote service entity. You can adjust the [projection for the association target](#model-projections) and change the name of the association: ```cds -using { API_BUSINESS_PARTNER as bupa } from '../srv/external/API_BUSINESS_PARTNER'; +using { API_BUSINESS_PARTNER as bupa } from '../srv/external/API_BUSINESS_PARTNER'; extend service RiskService with { entity Suppliers as projection on bupa.A_BusinessPartner { diff --git a/node.js/remote-services.md b/node.js/remote-services.md index 5199b85cc..eaf48173e 100644 --- a/node.js/remote-services.md +++ b/node.js/remote-services.md @@ -28,6 +28,32 @@ The `cds.RemoteService` configuration allows you to define various options for c +### HTTP Client {#http-client} + +CAP supports two HTTP clients for outgoing remote service calls: [SAP Cloud SDK](#sap-cloud-sdk) and CAP's built-in [native fetch client](#native-fetch). + +#### SAP Cloud SDK {#sap-cloud-sdk} + +If the SAP Cloud SDK HTTP client (`@sap-cloud-sdk/http-client`) is installed, CAP uses it by default. The client provides full support for all SAP BTP Destination service features including on-premise connectivity. + +[Learn more about SAP Cloud SDK.](https://sap.github.io/cloud-sdk/docs/js/overview){.learn-more} + +#### Native Fetch Client {#native-fetch} + +CAP provides a built-in remote client that uses the native Node.js `fetch` API, including support for resolving named destinations from the SAP BTP Destination service. + +::: warning Current limitations +The native fetch client supports only proxy type `Internet` and authentication types `NoAuthentication`, `BasicAuthentication`, and `OAuth2ClientCredentials`. Other authentication types are resolved on a best-effort basis via the native destination client. +::: + +You don't need SAP Cloud SDK for local development. For production, the SAP Cloud SDK is only required if you use authentication types or proxy configurations not yet supported by the native client. + +The client selection follows this priority: + +1. **Explicit configuration** - set cds.remote.native_fetch to `true` or `false`, CAP uses that setting. +2. **Default behavior** - CAP uses native fetch when you haven't installed `@sap-cloud-sdk/http-client`. + +[Learn more about SAP BTP Destination service support for the native fetch client.](../guides/integration/service-bindings#native-fetch-destinations){.learn-more} ### CSRF-Token Handling @@ -94,7 +120,7 @@ The `requestTimeout` setting in the `cds.RemoteService` configuration specifies ``` ::: tip -See [Using Destinations](../guides/services/consuming-services#using-destinations) for more details on destination configuration. +See [Using Destinations](../guides/integration/service-bindings#destinations) for more details on destination configuration. ::: ## More to Come