From 5c6d61a7195069ed2342e049769635939b8ed639 Mon Sep 17 00:00:00 2001 From: Mevan Date: Thu, 7 Nov 2024 17:19:04 +0530 Subject: [PATCH 1/3] Improve Docs for API-Key feature --- .../create-a-connection.md | 9 +++++-- .../use-a-connection-in-your-service.md | 27 +++++++++++++++++++ 2 files changed, 34 insertions(+), 2 deletions(-) diff --git a/en/docs/develop-components/sharing-and-reusing/create-a-connection.md b/en/docs/develop-components/sharing-and-reusing/create-a-connection.md index e706166cf..130fcc1c1 100644 --- a/en/docs/develop-components/sharing-and-reusing/create-a-connection.md +++ b/en/docs/develop-components/sharing-and-reusing/create-a-connection.md @@ -21,8 +21,13 @@ To create a connection to a service or a database, follow the step-by-step instr 3. Click **+Create**. This opens the Marketplace view where you can browse and search for services or databases. 4. Click the **Services** tab. You can search and apply filters to efficiently find a service. 5. Click on the service you want to connect to. - 6. Enter a name and a description for the connection and then click **Next**. This displays the **Service URL** for both development and production environments. - 7. Click **Create**. + 6. Enter a name and a description for the connection. + 7. Select **Access Mode** and **Authentication Scheme** for the connection. + + !!! note + API Key security scheme is not supported for Web App and External Consumer components. + + 8. Click **Create**. This creates the connection and displays its details for each environment, along with an inline guide on how to use the connection in your component. diff --git a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md b/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md index f91b6c3c8..af819b80c 100644 --- a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md +++ b/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md @@ -45,6 +45,7 @@ To integrate another service into your application, click the appropriate tab be | ConsumerKey | CHOREO__CONSUMERKEY | | ConsumerSecret | CHOREO__CONSUMERSECRET | | TokenURL | CHOREO__TOKENURL | + | ChoreoAPIKey | CHOREO_CHOREOAPIKEY | If you'd like to use custom environment variable names instead of the Choreo-defined ones, add the dependency as a service reference under `dependencies` in the same file. For more details, refer to the instructions under the `component.yaml file (v1.0)` tab. @@ -58,6 +59,7 @@ To integrate another service into your application, click the appropriate tab be | ConsumerKey | string | Consumer key of the Choreo service | false | false | | ConsumerSecret | string | Consumer secret of the Choreo service | false | true | | TokenURL | string | Token URL of the STS | false | false | + | ChoreoAPIKey | string | API key of the Choreo service | false | true | ### Step 2: Read configurations within the application @@ -93,6 +95,8 @@ To integrate another service into your application, click the appropriate tab be to: - from: TokenURL to: + - from: ChoreoAPIKey + to: ``` @@ -118,6 +122,7 @@ To integrate another service into your application, click the appropriate tab be | ConsumerKey | string | Consumer key of the Choreo service | false | false | | ConsumerSecret | string | Consumer secret of the Choreo service | false | true | | TokenURL | string | Token URL of the STS | false | false | + | ChoreoAPIKey | string | API key of the Choreo service | false | true |

Step 2: Read configurations within the application

@@ -153,6 +158,8 @@ To integrate another service into your application, click the appropriate tab be to: - from: TokenURL to: + - from: ChoreoAPIKey + to: ``` @@ -178,6 +185,7 @@ To integrate another service into your application, click the appropriate tab be | ConsumerKey | string | Consumer key of the Choreo service | false | false | | ConsumerSecret | string | Consumer secret of the Choreo service | false | true | | TokenURL | string | Token URL of the STS | false | false | + | ChoreoAPIKey | string | API key of the Choreo service | false | true |

Step 2: Read configurations within the application

@@ -189,6 +197,8 @@ To integrate another service into your application, click the appropriate tab be const serviceURL = process.env.SVC_URL; ``` +If you're using the API-Key security scheme for the connection, skip **Step 3** and proceed to **Step 4: Service secured with API Key**. + ### Step 3: Acquire an OAuth 2.0 access token To consume a Choreo service with the visibility level set to organization or public and secured by the OAuth 2.0 security scheme, you must obtain an OAuth 2.0 token from the token endpoint. Subsequently, you can use the token to invoke the service. @@ -215,6 +225,22 @@ To consume a Choreo service with the visibility level set to organization or pub ### Step 4: Invoke the Service +=== "Service secured with API Key" + +Invoke the API using the **choreo-api-key** header with the value obtained from the corresponding environment variable as described in [step 2](#step-2-read-configurations-within-the-application). + + The following is a sample code snippet in NodeJS: + + ``` java + const response = await axios.get(serviceURL/{RESOURCE_PATH}, { + headers: { + 'Choreo-API-Key': `${choreoApiKey}` + } + }); + ``` + +=== "Service secured with OAuth 2.0" + You can invoke the service as follows: - For languages with OAuth 2.0-aware HTTP clients, you can invoke the service in a straightforward manner. The HTTP client seamlessly manages OAuth 2.0 authentication without requiring additional intervention. @@ -230,6 +256,7 @@ As the service URL you can use the URL that you resolved in [step 2](#step-2-rea const response = await axios.get(serviceURL/{RESOURCE_PATH}, { headers: { 'Authorization': `Bearer ${accessToken}` + 'Choreo-API-Key': `${choreoApiKey}` } }); ``` From 4e37ba47ce52c75fb632ba683e405b4b9fb2baa4 Mon Sep 17 00:00:00 2001 From: Nisrin Date: Mon, 11 Nov 2024 11:13:38 +0530 Subject: [PATCH 2/3] Update use-a-connection-in-your-service.md --- .../use-a-connection-in-your-service.md | 54 +++++++++---------- 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md b/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md index af819b80c..6558e4bec 100644 --- a/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md +++ b/en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md @@ -197,7 +197,7 @@ To integrate another service into your application, click the appropriate tab be const serviceURL = process.env.SVC_URL; ``` -If you're using the API-Key security scheme for the connection, skip **Step 3** and proceed to **Step 4: Service secured with API Key**. +If you're using the API key security scheme for the connection, skip Step 3 and follow the instructions in [Step 4: API key security scheme](#step-4-invoke-the-service) tab. ### Step 3: Acquire an OAuth 2.0 access token @@ -223,44 +223,42 @@ To consume a Choreo service with the visibility level set to organization or pub ``` -### Step 4: Invoke the Service +### Step 4: Invoke the service -=== "Service secured with API Key" +Click the tab that matches the security scheme of your service and follow the instructions below: -Invoke the API using the **choreo-api-key** header with the value obtained from the corresponding environment variable as described in [step 2](#step-2-read-configurations-within-the-application). +=== "API key security scheme" - The following is a sample code snippet in NodeJS: + To invoke the API, use the `choreo-api-key` header with the API key value retrieved from the corresponding environment variable as described in [step 2](#step-2-read-configurations-within-the-application). - ``` java - const response = await axios.get(serviceURL/{RESOURCE_PATH}, { - headers: { - 'Choreo-API-Key': `${choreoApiKey}` - } - }); - ``` + The following is a sample code snippet in NodeJS: -=== "Service secured with OAuth 2.0" + ``` java + const response = await axios.get(serviceURL/{RESOURCE_PATH}, { + headers: { + 'Choreo-API-Key': `${choreoApiKey}` + } + }); + ``` -You can invoke the service as follows: +=== "OAuth 2.0 security scheme" -- For languages with OAuth 2.0-aware HTTP clients, you can invoke the service in a straightforward manner. The HTTP client seamlessly manages OAuth 2.0 authentication without requiring additional intervention. + To invoke the service, use the following instructions based on your programming language: - As the service URL you can use the URL that you resolved in [step 2](#step-2-read-configurations-within-the-application). For sample requests and responses, see the API definition provided via the Choreo marketplace for the service. + - For languages with OAuth 2.0-aware HTTP clients, use the service URL resolved in [Step 2](#step-2-read-configurations-within-the-application). The OAuth-aware client manages authentication automatically. For sample requests and responses, see the API definition provided via the Choreo marketplace for the service. -- For languages without OAuth 2.0-aware HTTP clients, you can use the token obtained in [step 3](#step-3-acquire-an-oauth-20-access-token) to make calls to the dependent service. Subsequently, add the obtained token to the HTTP authorization header with the bearer prefix. -As the service URL you can use the URL that you resolved in [step 2](#step-2-read-configurations-within-the-application). For sample requests and responses, see the API definition of the service provided via the Choreo marketplace. + - For languages without OAuth 2.0-aware HTTP clients, use the token obtained in [step 3](#step-3-acquire-an-oauth-20-access-token) to make calls to the dependent service. Subsequently, add the obtained token to the HTTP authorization header with the bearer prefix. As the service URL, use the URL resolved in [step 2](#step-2-read-configurations-within-the-application). For sample requests and responses, see the API definition of the service provided via the Choreo marketplace. - The following is a sample code snippet in NodeJS: + The following is a sample code snippet in NodeJS: - ``` java - const response = await axios.get(serviceURL/{RESOURCE_PATH}, { - headers: { - 'Authorization': `Bearer ${accessToken}` - 'Choreo-API-Key': `${choreoApiKey}` - } - }); - ``` + ``` java + const response = await axios.get(serviceURL/{RESOURCE_PATH}, { + headers: { + 'Authorization': `Bearer ${accessToken}` + 'Choreo-API-Key': `${choreoApiKey}` + } + }); + ``` !!! note If you want to consume a Choreo service at the project visibility level, you don't need to obtain a token. You can directly invoke the service using the resolved URL. - From 21868b4a82273364b37819796b246200740e5a25 Mon Sep 17 00:00:00 2001 From: Nisrin Date: Mon, 11 Nov 2024 11:19:09 +0530 Subject: [PATCH 3/3] Apply review suggestions --- .../sharing-and-reusing/create-a-connection.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/en/docs/develop-components/sharing-and-reusing/create-a-connection.md b/en/docs/develop-components/sharing-and-reusing/create-a-connection.md index 130fcc1c1..c019e123e 100644 --- a/en/docs/develop-components/sharing-and-reusing/create-a-connection.md +++ b/en/docs/develop-components/sharing-and-reusing/create-a-connection.md @@ -22,11 +22,7 @@ To create a connection to a service or a database, follow the step-by-step instr 4. Click the **Services** tab. You can search and apply filters to efficiently find a service. 5. Click on the service you want to connect to. 6. Enter a name and a description for the connection. - 7. Select **Access Mode** and **Authentication Scheme** for the connection. - - !!! note - API Key security scheme is not supported for Web App and External Consumer components. - + 7. Select an **Access Mode** and **Authentication Scheme** for the connection. 8. Click **Create**. This creates the connection and displays its details for each environment, along with an inline guide on how to use the connection in your component.