Skip to content

Commit

Permalink
Merge pull request #1658 from mevan-karu/api_key
Browse files Browse the repository at this point in the history 
Improve Docs for API-Key feature
  • Loading branch information
@Nashaath
Nashaath authored Nov 13, 2024
2 parents 217c87f + e6a622b commit 4845eac
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 17 deletions.
5 changes: 3 additions & 2 deletions en/docs/develop-components/sharing-and-reusing/create-a-connection.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
55 changes: 40 additions & 15 deletions en/docs/develop-components/sharing-and-reusing/use-a-connection-in-your-service.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ To integrate another service into your application, click the appropriate tab be
| ConsumerKey | CHOREO_<CONNECTION_NAME\>_CONSUMERKEY |
| ConsumerSecret | CHOREO_<CONNECTION_NAME\>_CONSUMERSECRET |
| TokenURL | CHOREO_<CONNECTION_NAME\>_TOKENURL |
| ChoreoAPIKey | CHOREO_<CONNECTION_NAME\>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.
Expand All @@ -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

Expand Down Expand Up @@ -93,6 +95,8 @@ To integrate another service into your application, click the appropriate tab be
to: <YOUR_ENV_VARIABLE_NAME_HERE>
- from: TokenURL
to: <YOUR_ENV_VARIABLE_NAME_HERE>
- from: ChoreoAPIKey
to: <YOUR_ENV_VARIABLE_NAME_HERE>

```

Expand All @@ -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 |

<h3> Step 2: Read configurations within the application </h3>

Expand Down Expand Up @@ -153,6 +158,8 @@ To integrate another service into your application, click the appropriate tab be
to: <YOUR_ENV_VARIABLE_NAME_HERE>
- from: TokenURL
to: <YOUR_ENV_VARIABLE_NAME_HERE>
- from: ChoreoAPIKey
to: <YOUR_ENV_VARIABLE_NAME_HERE>

```

Expand All @@ -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 |

<h3> Step 2: Read configurations within the application </h3>

Expand All @@ -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.
Expand All @@ -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.

0 comments on commit 4845eac

Please sign in to comment.