diff --git a/en/.spelling b/en/.spelling index 91a7e3745..a0df9473e 100644 --- a/en/.spelling +++ b/en/.spelling @@ -628,6 +628,7 @@ configure-an-external-idp configure-asgardeo-as-an-external-idp configure-azure-ad-as-an-external-idp test-apis-with-choreo-apichat +invoke-an-api - theme/material/templates/home-page.html doctype html @@ -781,3 +782,5 @@ AzureAD identity-as-a-soluton - docs/testing/test-apis-with-choreo-apichat.md findByStatus + - docs/consuming-services/consume-a-service.md +choreo-examples diff --git a/en/docs/consuming-services/consuming-a-sevice.md b/en/docs/consuming-services/consume-a-service.md similarity index 90% rename from en/docs/consuming-services/consuming-a-sevice.md rename to en/docs/consuming-services/consume-a-service.md index 71bdc61f5..9dadfd1f3 100644 --- a/en/docs/consuming-services/consuming-a-sevice.md +++ b/en/docs/consuming-services/consume-a-service.md @@ -4,10 +4,13 @@ Choreo is a platform that allows you to create, deploy, and consume services sea Typically, an application developer who may be internal or external to your organization would want to consume the APIs published in the Developer Portal to develop their applications. In this guide, you will learn how to discover, generate credentials, and test the consumption of a service published in the Choreo Developer Portal. You will also learn how to invoke the service via a web application. -This guide walks you through the following steps: +This is an end-to-end guide that walks you through the following steps: - Create an application in the Developer Portal and generate credentials for the application. - Subscribe the API to the application. +- Generate keys for your application. +- Generate an access token. +- Consume your published API via a cURL. - Consume a published REST API via your web application. ## Prerequisites @@ -45,7 +48,19 @@ The overview page of an API displays the subscribed versions of the API along wi {% include "create-a-subscription.md" %} -## Consume the API via your web application +## Generate an access token + +{% include "generate-an-access-token-body.md" %} + +## Consume the API + + You can consume an API using a cURL command in your web application. + +### Consume an via cURL + +{% include "consume-an-api-via-curl.md" %} + +### Consume an API via a web application You can invoke the API/service using the credentials you created above. Since Choreo services are secured, you need to invoke the services securely with the help of your IdP. To invoke the API/service you created securely, you need to follow the steps below: @@ -60,14 +75,14 @@ In this guide, you will be using the following product and examples: - [choreo-examples/cloud-native-app-developer/reading-list-front-end](https://github.com/wso2/choreo-examples/tree/main/cloud-native-app-developer/reading-list-front-end) as the web application. This is a React SPA that invokes the service using Axios. This web application is configured to read the [choreo-examples/cloud-native-app-developer/reading-list-service/](https://github.com/wso2/choreo-examples/tree/main/cloud-native-app-developer/reading-list-service) as the service. You can modify this web application to read your service, or [deploy the choreo-examples/cloud-native-app-developer/reading-list-service/](https://wso2.com/choreo/docs/quick-start-guides/build-your-first-cloud-native-application-with-choreo/#step-1-create-a-service-component-and-publish-it-as-a-rest-api) in Choreo and use it. -### Step 1: Create a web application component +#### Step 1: Create a web application component !!! info You can use your own web application implementation in place of the sample web application. For this exercise, let's use the [choreo-examples/cloud-native-app-developer/reading-list-front-end](https://github.com/wso2/choreo-examples/tree/main/cloud-native-app-developer/reading-list-front-end) as the web application. {% include "../quick-start-guides/create-web-application-qsg.md" %} -### Step 2: Create an OAuth application in the IdP +#### Step 2: Create an OAuth application in the IdP To invoke the service/API in Choreo you require a token. To obtain a token you need to create an OAuth application in the IdP. If you use any other IdP other than Asgardeo, create an OAuth application and set the following: @@ -92,14 +107,13 @@ Choreo uses Asgardeo as the default identity provider for Choreo applications. W 5. Under **Access Token**, select **JWT** as the **Token type**. 6. Click **Update**. -### Step 3: Configure the web application to connect to the IdP and invoke the service +#### Step 3: Configure the web application to connect to the IdP and invoke the service {% include "../quick-start-guides/configure-front-end-application-qsg.md" %} -### Step 4: Deploy the web application +#### Step 4: Deploy the web application {% include "../quick-start-guides/deploy-the-web-application-qsg.md" %} - That's it! You can use a user created in your IdP and invoke the service through your web application. diff --git a/en/docs/consuming-services/consume-an-api-via-curl.md b/en/docs/consuming-services/consume-an-api-via-curl.md new file mode 100644 index 000000000..e82040455 --- /dev/null +++ b/en/docs/consuming-services/consume-an-api-via-curl.md @@ -0,0 +1,11 @@ +You can invoke the API using the access token you generated above. Use the following cURL command template, fill in the required fields, and invoke the API. + +=== "Format" + ``` curl + curl -H "Authorization: Bearer " + ``` + +=== "Example" + ``` curl + curl -H "Authorization: Bearer eyJ4NXQiOiJaR1F6WXpaaE5XVTJZbVE1T0RBM....TueTTZ1qTwLgUL2Sivkjg" https://-dev.e1-us-east-azure.choreoapis.dev/xaxz/reading-list-service/readinglist-a57/1.0.0/books + ``` \ No newline at end of file diff --git a/en/docs/consuming-services/generate-an-access-token-body.md b/en/docs/consuming-services/generate-an-access-token-body.md new file mode 100644 index 000000000..e0c441893 --- /dev/null +++ b/en/docs/consuming-services/generate-an-access-token-body.md @@ -0,0 +1,26 @@ +### Generate an access token in cURL + +You can follow the steps below to generate an access token for your application via cURL: + +1. In the [Choreo Developer Portal](https://devportal.choreo.dev) header, click **Applications**. +2. On the **My Applications** page, click on the application for which you want to generate the token. +3. In the left navigation menu, click the required environment under **Credentials**. This opens the **Application Keys** pane of the specific environment. +4. Copy the **Consumer Key**, **Consumer Secret**, and **Token Endpoint** values. +5. Use the following template and compile the cURL command with the values you copied in the above step. + + === "Format" + ``` + curl -k -X POST -d "grant_type=client_credentials" -H "Authorization: Basic " + ``` +6. Execute the cURL command to generate an access token. + + +### Generate an access token in the Choreo Console (for testing purposes) + +You follow the steps below to generate an access token for **testing purposes**: + +1. In the [Choreo Developer Portal](https://devportal.choreo.dev) header, click **Applications**. +2. On the **My Applications** page, click on the application for which you want to generate keys and tokens. +3. In the left navigation menu, click the required environment under **Credentials**. This opens the **Application Keys** pane of the specific environment. +5. Click **Generate Token**. + diff --git a/en/docs/consuming-services/generate-an-access-token-via-curl.md b/en/docs/consuming-services/generate-an-access-token-via-curl.md new file mode 100644 index 000000000..e69de29bb diff --git a/en/docs/consuming-services/generate-an-access-token.md b/en/docs/consuming-services/generate-an-access-token.md index b9d0d5c8d..1c2e61564 100644 --- a/en/docs/consuming-services/generate-an-access-token.md +++ b/en/docs/consuming-services/generate-an-access-token.md @@ -16,10 +16,11 @@ Before you try out this guide, be sure you have the following: 2. [Generate keys for the application](https://wso2.com/choreo/docs/consuming-services/create-an-application/#step-2-generate-keys). 3. [Subscribe APIs to the application](https://wso2.com/choreo/docs/consuming-services/create-a-subscription/#manage-subscriptions). +## Generate an access token -## Generate an access token via cURL +You can generate an access token using a cURL command or a test token in the Choreo Console. Follow the steps below: -You can follow the steps below to generate an access token for your application via cURL: +{% include "generate-an-access-token-body.md" %} 1. In the [Choreo Developer Portal](https://devportal.choreo.dev) header, click **Applications**. 2. On the **My Applications** page, click on the application for which you want to generate the token. @@ -40,4 +41,4 @@ You can follow the steps below to generate an access token for **testing purpose 1. In the [Choreo Developer Portal](https://devportal.choreo.dev) header, click **Applications**. 2. On the **My Applications** page, click on the application for which you want to generate keys and tokens. 3. In the left navigation menu, click the required environment under **Credentials**. This opens the **Application Keys** pane of the specific environment. -4. Click **Generate Token**. \ No newline at end of file +4. Click **Generate Token**. diff --git a/en/docs/consuming-services/invoke-an-api.md b/en/docs/consuming-services/invoke-an-api.md new file mode 100644 index 000000000..e8273dea9 --- /dev/null +++ b/en/docs/consuming-services/invoke-an-api.md @@ -0,0 +1,13 @@ +# Invoke an API + +Choreo Service components, whether they function through REST, gRPC, Ballerina Service, TCP, UDP, or other protocols, can be exposed as APIs. In the Choreo ecosystem, API security is implemented through OAuth 2.0. Consequently, when making calls to an API, the invocation must include an OAuth 2.0 bearer token in the HTTP header of the request. This token serves as a means of authentication, ensuring secure access to the API. Known as the API Access Token or Key, this string is an essential component that must accompany the API + +This guide will walk you through the steps you need to follow to invoke an API in Choreo either via a cURL command or via your web application. + +## Invoke an API via cURL + +{% include "consume-an-api-via-curl.md" %} + +## Invoke and API via a web application + +You can consume an API via your web application. Refer the steps in the guide [Consume a Service - Consume an API via a web application ](hhttps://wso2.com/choreo/docs//choreo/docs/consuming-services/consume-a-service/#consume-an-api-via-a-web-application) to learn how you can consume the API via your web application. \ No newline at end of file diff --git a/en/mkdocs.yml b/en/mkdocs.yml index be1f8ce41..dd106b6b0 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -136,10 +136,11 @@ nav: - Test APIs using Postman: testing/test-apis-using-postman.md - Test APIs with Choreo API Chat: testing/test-apis-with-choreo-apichat.md - Consuming Services: - - Consume a Service: consuming-services/consuming-a-sevice.md + - Consume a Service: consuming-services/consume-a-service.md - Manage Application: consuming-services/manage-application.md - Manage Subscription: consuming-services/manage-subscription.md - Generate an Access Token: consuming-services/generate-an-access-token.md + - Invoke an API: consuming-services/invoke-an-api.md - API Management: - Lifecycle Management: api-management/lifecycle-management.md - Documents: api-management/documents.md @@ -288,6 +289,7 @@ plugins: 'consume/manage-application.md': 'https://wso2.com/choreo/docs/consuming-services/manage-application/' 'consume/manage-subscription.md': 'https://wso2.com/choreo/docs/consuming-services/manage-subscription/' 'consume/test-api.md': 'https://wso2.com/choreo/docs/testing/test-rest-endpoints-via-the-openapi-console/' + 'consume/consuming-a-sevice.md': 'https://wso2.com/choreo/docs/consuming-services/consume-a-service/' 'marketplace.md': 'https://wso2.com/choreo/docs/choreo-concepts/choreo-marketplace/' 'observe-and-analyze/observe/observability-overview.md': 'https://wso2.com/choreo/docs/monitoring-and-insights/observability-overview/' 'observe-and-analyze/observe/root-cause-analysis.md': 'https://wso2.com/choreo/docs'