From c6e220dfa0a97fa88cdc1fbfabaca772891591bf Mon Sep 17 00:00:00 2001 From: shani Ranasinghe Date: Mon, 23 Oct 2023 09:37:30 +0530 Subject: [PATCH 1/5] updated --- en/.spelling | 3 ++ ...uming-a-sevice.md => consume-a-service.md} | 28 ++++++++++++++----- .../consume-an-api-via-curl.md | 13 +++++++++ .../generate-an-access-token-body.md | 26 +++++++++++++++++ .../generate-an-access-token-via-curl.md | 0 .../generate-an-access-token.md | 7 +++-- en/docs/consuming-services/invoke-an-api.md | 13 +++++++++ en/mkdocs.yml | 3 +- 8 files changed, 82 insertions(+), 11 deletions(-) rename en/docs/consuming-services/{consuming-a-sevice.md => consume-a-service.md} (90%) create mode 100644 en/docs/consuming-services/consume-an-api-via-curl.md create mode 100644 en/docs/consuming-services/generate-an-access-token-body.md create mode 100644 en/docs/consuming-services/generate-an-access-token-via-curl.md create mode 100644 en/docs/consuming-services/invoke-an-api.md 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..14069ee4a 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 guide 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..3e7f40e6f --- /dev/null +++ b/en/docs/consuming-services/consume-an-api-via-curl.md @@ -0,0 +1,13 @@ +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..a77ff8023 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..bfeaaf8f1 --- /dev/null +++ b/en/docs/consuming-services/invoke-an-api.md @@ -0,0 +1,13 @@ +# Invoke an API + +You can expose a Choreo Service component (REST, gRPC, Ballerina Service, TCP, UDP, etc.) as an API. An API in Choreo is secured using OAuth 2.0. Therefore to invoke an API, the API invocation call needs to include an OAuth2.0 bearer token alongside the API request in order to authenticate the access. An API Access Token/Key is a string that is passed as an HTTP header of an API request. + +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..40ad8fae0 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 From 36600303652a059a382804fa462d83d737f9f1e1 Mon Sep 17 00:00:00 2001 From: shani Ranasinghe Date: Mon, 23 Oct 2023 09:40:35 +0530 Subject: [PATCH 2/5] add redirection --- en/mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/en/mkdocs.yml b/en/mkdocs.yml index 40ad8fae0..dd106b6b0 100644 --- a/en/mkdocs.yml +++ b/en/mkdocs.yml @@ -289,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' From 57a81bafa9a85cab9836547635b80441dd4ba878 Mon Sep 17 00:00:00 2001 From: shani Ranasinghe Date: Mon, 23 Oct 2023 09:49:57 +0530 Subject: [PATCH 3/5] Fix issues --- en/docs/consuming-services/consume-an-api-via-curl.md | 2 -- en/docs/consuming-services/invoke-an-api.md | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/en/docs/consuming-services/consume-an-api-via-curl.md b/en/docs/consuming-services/consume-an-api-via-curl.md index 3e7f40e6f..e82040455 100644 --- a/en/docs/consuming-services/consume-an-api-via-curl.md +++ b/en/docs/consuming-services/consume-an-api-via-curl.md @@ -4,8 +4,6 @@ You can invoke the API using the access token you generated above. Use the follo ``` curl curl -H "Authorization: Bearer " ``` - - === "Example" ``` curl diff --git a/en/docs/consuming-services/invoke-an-api.md b/en/docs/consuming-services/invoke-an-api.md index bfeaaf8f1..e8273dea9 100644 --- a/en/docs/consuming-services/invoke-an-api.md +++ b/en/docs/consuming-services/invoke-an-api.md @@ -1,6 +1,6 @@ # Invoke an API -You can expose a Choreo Service component (REST, gRPC, Ballerina Service, TCP, UDP, etc.) as an API. An API in Choreo is secured using OAuth 2.0. Therefore to invoke an API, the API invocation call needs to include an OAuth2.0 bearer token alongside the API request in order to authenticate the access. An API Access Token/Key is a string that is passed as an HTTP header of an API request. +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. From eab8d632434191b533bbb957fb8c108f7dcb1473 Mon Sep 17 00:00:00 2001 From: Shani Ranasinghe Date: Fri, 8 Dec 2023 15:18:00 +0530 Subject: [PATCH 4/5] Update consume-a-service.md --- en/docs/consuming-services/consume-a-service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/docs/consuming-services/consume-a-service.md b/en/docs/consuming-services/consume-a-service.md index 14069ee4a..9dadfd1f3 100644 --- a/en/docs/consuming-services/consume-a-service.md +++ b/en/docs/consuming-services/consume-a-service.md @@ -4,7 +4,7 @@ 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 is an end-to-end guide that 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. From 2489639ceab84b98bb88246f8ab9c16347e93793 Mon Sep 17 00:00:00 2001 From: Shani Ranasinghe Date: Fri, 8 Dec 2023 15:18:15 +0530 Subject: [PATCH 5/5] Update en/docs/consuming-services/generate-an-access-token.md Co-authored-by: Nisrin --- en/docs/consuming-services/generate-an-access-token.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/docs/consuming-services/generate-an-access-token.md b/en/docs/consuming-services/generate-an-access-token.md index a77ff8023..1c2e61564 100644 --- a/en/docs/consuming-services/generate-an-access-token.md +++ b/en/docs/consuming-services/generate-an-access-token.md @@ -18,7 +18,7 @@ Before you try out this guide, be sure you have the following: ## Generate an access token -You can generate an access token using a cURL command or a test token in the Choreo console. Follow the steps below: +You can generate an access token using a cURL command or a test token in the Choreo Console. Follow the steps below: {% include "generate-an-access-token-body.md" %}