Consume a Service

Choreo is a platform that allows you to create, deploy, and consume services seamlessly. The Choreo Developer Portal simplifies discovering and using APIs for API consumers.

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:

• Create an application in the Developer Portal and generate credentials for the application.
• Subscribe the API to the application.
• Consume a published REST API via your web application.

Prerequisites

Before you try out this guide, if you do not have a published service that you would want to consume via the Developer Portal, follow Develop a Service documentation to publish and deploy a sample REST API.

Discover APIs

In the Choreo Developer Portal, developers can use the search option to find APIs by name. The APIs and services that are created and published through the Choreo Console become visible in the Developer Portal depending on the API's visibility as follows:

• Public: The API is visible to all in the developer portal.

• Private: The API is visible to the users who only sign in to the Developer Portal.

• Restricted: The API is visible to only the user that has the roles that you specify. This option helps developers to enforce fine-grained access control to the API.

To learn more about API visibility, see Control API Visibility.

The Choreo Developer Portal lists APIs based on their major version.

The overview page of an API displays the subscribed versions of the API along with the respective subscription details such as the subscribed application and the application creation date.

Tip

If you want to use an API, the recommended approach is to use the latest version of it. You can copy the major version pattern provided as the value of Endpoints(s) on the API overview page and use it in your client application. This ensures that your application always invokes the latest API version.

Create an application

An application in Choreo is a logical representation of a physical application such as a mobile app, web app, device, etc. To consume an API in Choreo, you need to create an application that maps to your physical application and then subscribes to the required API over a usage policy plan that gives you a usage quota. A single application can have multiple subscriptions to APIs. Using the consumer key and consumer secret, you can generate an access token that you can use to invoke all the APIs subscribed to the same application.

This section walks you through the steps to create an application in Choreo.

Let's get started!

Step 1: Create an application

To create an application in the Choreo Developer Portal, follow the steps given below:

1. Sign in to the Choreo Developer Portal.
2. Click Applications. and then click +Create.
3. Enter a name and description for the application.
4. Click Create.

This creates the application and opens the application overview page. You can view details such as the token type, workflow status, and the application owner of the API.

Step 2: Generate keys

Choreo provides an OAuth 2.0 bearer token-based authentication for API access. An API access token/key is a string that is passed as an HTTP header of an API request to authenticate access to the API.

Once you create an application in Choreo, you can generate credentials for it. When you generate credentials for the first time, Choreo provides a consumer key and consumer secret for the application. The consumer key becomes the unique identifier of the application and is used to authenticate the application.

The following section walks you through the steps to generate an API access token in Choreo.

Generate environment-specific keys and tokens

You can generate keys and tokens to invoke production and non-production endpoints separately.

Note

The capability to access production endpoints depends on your role. If you have permission to access production endpoints, you can generate keys and tokens to invoke production endpoints.

1. In the Choreo Developer Portal 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 to expand Advanced Configurations and review the options.

   • Grant Types: Select the grant types to use when generating the access token.
   • Public Client: Select Allow authentication without the client secret if your application can be considered as a public client such as an application running on a browser or mobile device.
   • PKCE for enhanced security: Select Mandatory if you want the application to send a code challenge in the authorization request and the corresponding code verifier in the token request. Asgardeo supports SHA-256 and plain.
   • Application access token expiry time: Specify the access token expiry time in seconds.
   • Refresh token expiry time: Specify the refresh token expiry time in seconds.
   • ID token expiry time: Specify the ID token expiry time in seconds.

5. Click Generate Credentials. This opens the Application Keys pane with values populated for the credentials.

You can use this consumer key and consumer secret values to generate an API access token by invoking the token endpoint. You can also revoke the access token by invoking the revoke endpoint.

To generate a test token for testing purposes, you can click Generate Token and copy the test token that is displayed. Alternatively, click cURL and copy the generated cURL command to use via a cURL client and obtain a test token.

Warning

Make sure you do not use the test token in your production environment.

Subscribe to an API

You must subscribe to a published API to use it in your application. New API subscriptions cover all minor versions within the subscribed API’s major version.

The subscription process is designed to ensure the secure authentication of API requests via application keys. Alternatively, you can generate credentials for an API without an explicit subscription to an application. However, this approach limits the capability to control advanced configurations such as access token expiry time, revoke token expiry time, ID token expiry time, and enabling access to the API without a secret. Generating keys in the API is recommended for testing or short-term usage but not for long-term production usage.

To subscribe to an API via an application, follow the steps given below:

1. Sign in to the Choreo Developer Portal.
2. In the Developer Portal header, click Applications.
3. On the My Applications page, click on the application with which you want to subscribe to an API.
4. In the left navigation menu, click Subscriptions.
5. In the Subscription Management pane that opens, click + Add APIs.

6. Click Add to subscribe to an API. Depending on your requirement, you can subscribe to one or more APIs.

   Tip

   When a new minor version of an API is published, the major version-based invocation URL will automatically route to the latest minor version within the subscribed API's major version. This ensures that existing client applications can continue to function without disruption while benefiting from the improvements or additions in the newer minor version.

   

   Once you subscribe to an API, you can invoke the API using the application keys.

Consume the API via your 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:

1. Create a web application in Choreo.
2. Create an OAuth application in the IdP.
3. Configure the web application to authenticate the API/service invocations from the IdP, and securely invoke the service/API in Choreo.
4. Deploy the web application.

In this guide, you will be using the following products and examples:

• WSO2 Asgardeo as the IdP
• choreo-samples/reading-list-app/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-samples/reading-list-app/reading-list-service as the service. You can modify this web application to read your service, or deploy the choreo-samples/reading-list-app/reading-list-service in Choreo and use it.

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-samples/reading-list-app/reading-list-front-end as the web application.

To host the front-end application in Choreo, you must create a web application component. To create a web application component, follow the steps given below.

1. In the Choreo console, select the project of the reading list application that you created in the previous steps, from the project list located on the header.
2. Click Create under the Component Listing section to create a new component.
3. On the Web Application card, click Create.

4. Enter a unique name and a description for the web application. You can enter the name and description given below:

   Field	Value
   Name	Reading List Web App
   Description	Frontend application for the reading list service

5. Click Next.

6. To allow Choreo to connect to your GitHub account, click Authorize with GitHub.

7. In the Connect Repository pane, enter the following information:

   Field	Description
   GitHub Account	Your account
   GitHub Repository	choreo-samples
   Branch	main
   Buildpack	Click React since the frontend is a React application built with Vite
   Build Context Path	reading-list-app/reading-list-front-end
   Build Command	npm install && npm run build
   Build Output	dist
   Node Version	18

8. Click Create. This initializes the service with the implementation from your GitHub repository and takes you to the Overview page of the component.

Let's consume the service through the web app. Choreo services are by default secured. To consume a service in Choreo you need an access token. Let's configure the web application to connect to an IdP (For this guide, let's use Asgardeo) to generate an access token for a user.

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:

• Allowed grant types: Code
• Public client: Mark as a public client in an application.
• Authorized redirect URLs: Enter the web app URL you copied earlier.
• Allowed origins field: Add the same URLs that you added as authorized redirect URLs.
• Access Token: Set JWT as the Token type.

Choreo uses Asgardeo as the default identity provider for Choreo applications. When you create an application in the Choreo Developer Portal, it automatically creates a corresponding application in Asgardeo. You can go to the Asgardeo application to specify the configurations required for end users to sign in to the front-end application. Follow the steps below to configure the Asgardeo OAuth application:

1. Access Asgardeo at https://console.asgardeo.io/ and sign in with the same credentials with which you signed in to Choreo.
2. Make sure you are in the same organization that you were when you created the application in the Choreo Developer Portal. You can click the Organization list in the Asgardeo Console top menu and ensure you are in the correct organization.
3. In the Asgardeo Console's left navigation, click Applications. You will see the readingListApp that Choreo automatically created for you.
4. Click on the edit icon to edit the application.

5. Click the Protocol tab and apply the following changes:

   1. Under Allowed grant types, select Code.
   2. Select the Public client checkbox.
   3. In the Authorized redirect URLs field, enter the web app URL you copied earlier and click the + icon to add the entry.
   4. In the Allowed origins field, add the same URLs that you added as authorized redirect URLs.
   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

In this step, you are adding the configurations needed for the web app to successfully invoke the Reading List Service REST API. These configurations need to be updated for each environment you deploy the web app. Here you will be updating the configurations for the development environment.

Note

The web application is reading the environment-specific configurations from the window object at runtime. This is done via the config.js file in the root of the web application. In this section, you will mount the config.js file for the development environment. You will need to do the same for other environments as well when you deploy your web application to multiple environments.

To configure the front-end application, follow the steps given below:

1. While on the web application component page, click DevOps in the left navigation menu and then click Configs and Secrets.
2. Click + Create.

3. Select the mount configuration options as follows and click Next:

   Field	Description
   Config Type	Config Map
   Mount Type	File Mount

4. Specify values as follows for the mount configuration:

   Field	Description
   Config Name	Web App Config
   Mount Path	/usr/share/nginx/html/config.js. Every config that needs to be exposed through the web server should be placed inside /usr/share/nginx/html/

5. Copy the config details as a JSON file as shown below into the text area. Fill the placeholders with the values you copied from the previous steps as mentioned in the table below:

   window.config = {
       redirectUrl: "<web-app-url>",
       asgardeoClientId: "<asgardeo-client-id>",
       asgardeoBaseUrl: "https://api.asgardeo.io/t/<your-org-name>",
       choreoApiUrl: "<reading-list-service-url>"
   };
   

   Field	Description
   redirectUrl	The web app URL you copied earlier.
   asgardeoClientId	The Client ID of your OAuth application. In Asgardeo, you can find it on the Protocol tab of the readingListApp application
   asgardeoBaseUrl	Specify the IdP API URL (For example, Asgardeo API URL) with your organization name. i.e., https://api.asgardeo.io/t/<ORG_NAME>.
   choreoApiUrl	The reading list service URL. Copy the Public URL of the Reading List Service component from the endpoint table in the overview page for the relevant environment

6. Click Create.

Now you can proceed to deploy the web application.

Step 4: Deploy the web application

To deploy the web application component, follow the steps below:

1. In the left menu, click Deploy.
2. In the Build Area card, click Deploy Manually. The deployment may take a few minutes to complete.
3. Once the web application is deployed, copy the Web App URL from the development environment card.
4. Navigate to the web app URL. You can verify that the web app is successfully hosted.

That's it! You can use a user created in your IdP and invoke the service through your web application.