From 97b8012ec9805e071f26a721fe11cb893fb0e74f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Alexander=20D=C3=BCmont?=
 <22489773+newtork@users.noreply.github.com>
Date: Mon, 9 Sep 2024 10:55:40 +0200
Subject: [PATCH] doc: Add explanation for service binding options (#35)

* Initial

* Minor

* Add suggested changes
---
 README.md | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 73 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index f0d078e4..972872de 100644
--- a/README.md
+++ b/README.md
@@ -478,14 +478,55 @@ DeploymentApi api = new DeploymentApi(client);
 
 For more customization, creating a [HeaderProvider](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/http-destinations#about-headerproviders) is also possible.
 
-## Requirements and Setup
+## Requirements and Setup for AI Core
 
-### Set AI Core credentials as environment variable
+For any AI Core service interaction, the SAP AI SDK requires credentials to be available at application runtime.
+By default, the credentials are extracted automatically from a service instance of type "aicore" bound to the application. 
+Running the application locally without this service binding will throw an exception:
 
-- Running the application locally without a service binding will throw:
+```
+Could not find any matching service bindings for service identifier 'aicore'
+```
+
+There are multiple options to register the service binding:
+* Regular service binding in SAP BTP Cloud Foundry (resulting in `VCAP_SERVICES` env var entry).
+* Set an environment variable explicitly: `AICORE_SERVICE_KEY`
+* Define and use a _Destination_ in _BTP Destination Service_.
+* (For CAP applications) use the [hybrid testing](https://cap.cloud.sap/docs/advanced/hybrid-testing#services-on-cloud-foundry) approach _(not recommended for production)_.
+  * For example: `cds bind --to aicore --exec mvn spring-boot:run`
+* Leveraging `"user-provided"` service binding _(not recommended for production)_.
+* Define and use a custom `ServiceBinding` or `ServiceBindingAccessor` declaration in application _(not recommended for production)_.
+
+### Regular service binding in SAP BTP Cloud Foundry
+
+* Bind an existing service instance of type `aicore` to your application.
+  [With SAP BTP multiple options are available](https://help.sap.com/docs/btp/sap-business-technology-platform/binding-service-instances-to-applications): using the web interface, the CLI, MTA or manifest.
+
+<details><summary>After application restart, there should be an "aicore" entry in environment variable <code>VCAP_SERVICES</code>.</summary>
+
+```json
+{
+  "aicore": [
+      {
+        "clientid": "...",
+        "clientsecret": "...",
+        "url": "...",
+        "identityzone": "...",
+        "identityzoneid": "...",
+        "appname": "...",
+        "serviceurls": {
+          "AI_API_URL": "..."
+        }
+      }
+  ]
+}
+```
+
+</details>
+
+### Set credentials as dedicated environment variable
 
-  `Could not find any matching service bindings for service identifier 'aicore'`
-- Go into the BTP Cockpit
+- Go into the SAP BTP Cockpit
 - Instances and Subscriptions -> Instances -> AI Core -> View Credentials -> Copy JSON
 - Set it as an environment variable `AICORE_SERVICE_KEY` in your IDE
 
@@ -494,7 +535,33 @@ For more customization, creating a [HeaderProvider](https://sap.github.io/cloud-
 export AICORE_SERVICE_KEY='{   "serviceurls": {     "AI_API_URL": ...'
 ```
 
-### Run the Spring Boot application
+### Define and use a Destination
+
+* Lookup service-key credentials as explained in the previous step for `AICORE_SERVICE_KEY`.
+
+* <details><summary>Define a new destination in the SAP BTP Destination Service using the service-key credentials</summary>
+  
+  * (Destinations can be added on subaccount level and on service instance level.)
+  * (The URL field requires an additional path segment: `/v2`)
+  * **Name**: _my-aicore_
+  * **Type**: HTTP
+  * **URL**: _[serviceurls.AI_API_URL]/v2_
+  * **Proxy-Type**: Internet
+  * **Authentication**: _Oauth2ClientCredentials_
+  * **Client ID**: _[clientid]_
+  * **Client Secret**: _[clientsecret]_
+  * **Token Service URL Type**: Dedicated
+  * **Token Service URL**: _[url]_
+  
+  </details>
+
+* At application runtime the following can be executed:
+  ```java
+  Destination destination = DestinationAccessor.getDestination("my-aicore");
+  ApiClient client = Core.getClient(destination);
+  ```
+
+### Run the Spring Boot test application
 
 ```shell
 cd e2e-test-app