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..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 @@ -21,8 +21,9 @@ 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 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. 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..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 @@ -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 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 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. @@ -213,27 +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 -You can invoke the service as follows: +Click the tab that matches the security scheme of your service and follow the instructions below: -- 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. +=== "API key security scheme" - 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. + 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). -- 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. + 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: { + 'Choreo-API-Key': `${choreoApiKey}` + } + }); + ``` - ``` java - const response = await axios.get(serviceURL/{RESOURCE_PATH}, { - headers: { - 'Authorization': `Bearer ${accessToken}` - } - }); - ``` +=== "OAuth 2.0 security scheme" + + To invoke the service, use the following instructions based on your programming language: + + - 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, 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: + + ``` 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. -