Build Your First Cloud Native Application with Choreo¶

Choreo is a SaaS application development suite that allows you to effortlessly build, deploy, monitor, and manage your cloud native applications.

In this quick start guide, you will explore how to expose a service endpoint as a REST API via Choreo and securely consume the API from a web application. You will build a simple reading list web application with a sign-in page and functionality to interact with a secure backend REST API. You will use Asgardeo, WSO2's Identity as a Service (IDaaS) solution, to secure user authentication to the web application. The application will allow users to sign in and view the reading list. On signing in, a user can add books to a reading list and delete books from the reading list. The application will also allow users to sign out of the application.

This guide walks you through the following steps:

Develop, deploy, and test a service component.
Publish the service endpoint as a REST API for your web application to consume.
Expose the REST API via Choreo API management.
Securely consume the published REST API via your web application.
Deploy your web application and use Asgardeo as the IDaaS provider to secure user authentication to the web application.

Prerequisites¶

Before you try out this guide, complete the following:

Create a GitHub repository to save the service implementation. For this guide, you can fork https://github.com/wso2/choreo-examples.
If you are signing in to the Choreo Console for the first time, create an organization as follows:
1. Go to https://console.choreo.dev/, and sign in using your Google, GitHub, or Microsoft account.
2. Enter a unique organization name. For example, Stark Industries.
3. Read and accept the privacy policy and terms of use.
4. Click Create.
This creates the organization and opens the Project Home page of the default project created for you.
Enable Asgardeo as the key manager

If you created your organization in Choreo before the 21^st of February 2023, and you have not already enabled Asgardeo as the key manager, follow these steps to enable Asgardeo as the default key manager:
1. In the Choreo Console, click your username in the top right corner.
2. In the drop-down menu, click Settings.
3. In Settings, click API Management and then click Enable Asgardeo Key Manager.
4. In the confirmation dialog that opens, click Yes.

Step 1: Create a service component and publish it as a REST API¶

In this step, you are playing the role of an API developer. You will create a service and publish it as a REST API for your web application to consume.

Step 1.1: Create the service¶

Follow the steps below to create the service:

Go to https://console.choreo.dev/cloud-native-app-developer and sign in. This opens the Project Home page.
If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.
Go to the Service card and click Create.
Enter a unique name and a description for the service. You can enter the name and description given below:

Field Value

Name Reading List Service

Description Manages reading lists
Click Next.
To allow Choreo to connect to your GitHub account, click Authorize with GitHub.
If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials, and select the repository you created by forking https://github.com/wso2/choreo-examples to install the Choreo GitHub App.

Info

The Choreo GitHub App requires the following permissions:

- Read and write access to code and pull requests.

- Read access to issues and metadata.

You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is only used to send pull requests to a user repository. Choreo will not directly push any changes to a repository.

In the Connect Repository pane, enter the following information:

Field	Description
GitHub Account	Your account
GitHub Repository	`choreo-examples`
Branch	`main`
Build Preset	Click Ballerina because you are creating the REST API from a Ballerina project, and Choreo needs to run a Ballerina build to build it.
Path	`cloud-native-app-developer/reading-list-service`

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

Step 1.2: Deploy the service¶

For the REST endpoint of the service to be invokable, you need to deploy it. To deploy the service, follow the steps given below:

In the left navigation menu, click Deploy.
In the Build Area card, click Deploy Manually.
In the Configure & Deploy pane that opens, you can see the Readinglist endpoint ready to be deployed. Click the edit icon next to the Readinglist endpoint.
Change the Network Visibility to Public. This allows you to securely expose the endpoint to your web application.
Click Update.

Info

In this example, you deploy a Ballerina service as a REST endpoint. Therefore, the REST endpoint is generated automatically. If you deploy a non-Ballerina service, you must manually add the REST endpoint and set the network visibility to Public.
Click Deploy. This deploys the REST endpoint of the service to the development environment.

Step 1.3: Test the service¶

To test the Readinglist REST endpoint via the integrated OpenAPI Console in Choreo, follow the steps given below:

In the left navigation menu, click Test.
In the OpenAPI Console pane that opens, select Development from the environment drop-down list.
In the Public Endpoint list, select Readinglist.
Expand the GET method and click Try it out.
Click Execute.
Check the Server Response section. You will see a response similar to the following:
```
{
"error": "Bad Request",
"error_description": "Error while getting the JWT token"
}
```
To fix the JWT error response, you must enable passing the security context to the backend service through API management. You can proceed to the next section to fix the JWT error and publish the service.

Step 1.4: Publish the service¶

To fix the JWT error, retest the API, and publish the service, follow the steps given below:

Step 1.4.1: Update the CORS configuration and fix the JWT error

Let's assume you deploy the web application in a cloud platform such as Vercel. In such a scenario, you would want to call the Readinglist backend service deployed in Choreo through the web application on a Vercel domain. By default, web browsers block such calls for security reasons. To enable the web application to call the backend service, you must update the CORS configuration as follows:

In the left navigation menu, click Manage, and then click Settings.
Under API Settings, click Edit.
Click the CORS Configuration toggle to enable the setting.
Select the Access Control Allow Credentials checkbox.
To allow passing security context to the backend service, click the Pass Security Context To Backend toggle to enable the setting.
Click Save.
In the Apply to Development pane that opens, enter a meaningful message and click Apply.

Now you can retest the API to confirm that it works as expected.

Step 1.4.2: Retest the API

To retest the API, follow the steps given below:

In the left navigation menu, click Test.
In the OpenAPI Console pane that opens, select Development from the environment drop-down list.
In the Public Endpoint list, select Readinglist.
Expand the POST method and click Try it out.
Update the request body so that the parameters have the values given below:

Parameter Value

author Bram Stoker

status to_read

title Dracula

The request body should look as follows:
```
  {
    "author": "Bram Stoker",
    "status": "To Read",
    "title": "Dracula"
  }
```
Click Execute.

Check the Server Response section. On successful invocation, you will receive the 200 HTTP code.

Similarly, you can expand and try out the GET and DELETE methods.

Step 1.4.3: Publish the service endpoint as a REST API

To publish the REST endpoint and make it available for web application to consume, follow the steps given below:

In the Manage view, click Lifecycle.
Click Publish to publish the REST API to the Developer Portal. External applications can subscribe to the API via the Developer Portal.
To access the Developer Portal, click Go to DevPortal.

The Reading List Service REST API opens in the Developer Portal.

Step 2: Consume the REST API¶

You have published the Reading List Service REST API to the Developer Portal where application developers can find it and subscribe their applications to it.

In the previous steps, you played the role of backend developer and developed a service. In this step, you will play the role of the web application developer who consumes the service.

To consume the Reading List Service REST API, you must create an application, subscribe it to the REST API, generate keys, and invoke the API.

Step 2.1: Create an application¶

An application in the Developer Portal is a logical representation of a physical application such as a mobile application, web application, device, etc.

To create an application to consume the Reading List Service REST API, follow the steps given below:

In the top menu of the Developer Portal, click Applications.
Click Create.
Enter a name for the application (for example, readingListApp and click Create. This creates the application and takes you to the application overview page.
On the left navigation menu, click Production under Credentials.
Click Generate Credentials. This generates credentials for the application.

To consume the Reading List Service REST API, your application must subscribe to it. To subscribe to the API from the application, follow the steps given below:

In the left navigation menu, click Subscriptions.
Click Add APIs.
Find your REST API and click Add.

Now your application has subscribed to the Reading List Service REST API.

Step 2.3: Deploy a web application and invoke the REST API¶

At the moment, any user can invoke the Reading List Service REST API via the readingListApp application (i.e., using its token) and update the reading list. However, if a user sends a request to retrieve the reading list, the response will also show entries by other users. To allow multiple users to use the application and maintain personal reading lists, you need a front-end application that allows each user to sign in with a unique user ID.

In this step, let's deploy a predesigned front-end application. This application is designed to personalize the reading lists based on the user ID that it obtains from its identity provider. To enable the application to obtain the user ID, let's configure Asgardeo as the identity provider.

Step 2.3.1: Configure Asgardeo to integrate with your application

Choreo uses Asgardeo as the 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.

Access Asgardeo at https://console.asgardeo.io/ and sign in with the same credentials with which you signed in to Choreo.
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.
In the Asgardeo Console, click Develop and then click Applications. You will see the readingListApp that is automatically created.
Click on the application to edit it.
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 http://localhost:5173 and click the + icon to add the entry.
  
  Note
  
  The http://localhost:5173 entry is to try out the web application locally. When you deploy your web application to Vercel, you must add the Vercel web application URL as an authorized redirect URL.
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 2.3.2: Configure the front-end application

In this step, you must define the ports it needs to run on, add the endpoint to the Reading List Service REST API, etc.

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

Clone your fork of https://github.com/wso2/choreo-examples.

Open the cloned repository using an IDE such as Visual Studio Code, and make the following changes:

Expand the cloud-native-app-developer folder. Then expand the reading-list-front-end folder, and click the .env.development file.

Enter values for the parameters in the .env.development file, as specified in the following table:

Parameter	Value to specify
`VITE_REDIRECT_URL`	Specify `http://localhost:5173` to try out the web application locally. When you deploy on Vercel, specify the Vercel web application URL.
`VITE_ASGARDEO_CLIENT_ID`	Copy the Client ID from the Protocol tab of the readingListApp application in Asgardeo and paste the value.
`VITE_ASGARDEO_BASE_URL`	Specify the Asgardeo API URL with your organization name. i.e., `https://api.asgardeo.io/t/<ORG_NAME>`.
`VITE_CHOREO_BACKEND_URL`	Go to the Reading List Service component overview page in the Choreo Console and copy the Public URL under Endpoints. Make sure you copy the URL from the specific environment you want.

Save the changes.

Now you have configured your front-end application. Next, you must configure Asgardeo as the identity provider for your application.

Step 2.3.3: Create a user in Asgardeo

To sign in to the readingListApp application and create private reading lists, the end users require user IDs. End users can self-register these user IDs in Asgardeo or request an Asgardeo user with administrative privileges to register them. For more information, see Asgardeo Documentation - Manage users.

In this step, you play the role of an Asgardeo user with administrative privileges who can register user IDs.

To define a user for the readingListApp application, follow the steps given below:

Go to the Asgardeo Console, click Manage and then click Users.
On the Users page, click Add User.
In the Add User dialog, enter values for Username (Email), First Name, and Last Name.
Under Select the method to set the user password, select Invite the user to set the user password, and make sure you select Invite Via Email.
Click Finish.

Asgardeo will send you an email to set your password. It will also open your user profile on a separate page.
In your user profile, toggle the Lock User switch to unlock your profile.
In the email you receive from Asgardeo (with the subject Here is your new account in the organization ), click Set Password.
In the Enter new password and Confirm password fields, enter a password that complies with the given criteria, and then click Proceed.

Tip

You can create multiple users to test your front-end application.

Step 2.3.4: Invoke the REST API

To run the front-end application and send requests to the Reading List Service REST API via it, follow the steps given below:

Info

To render the front-end application as a web application, you can use the Node Package Manager software.

In a new terminal, navigate to the choreo-reading-list-application-example/reading-list-front-end directory in the clone of your GitHub repository.
Issue the following commands in the given order:
- npm i
  
  This command installs the latest Node Package Manager version in the local directory where you have the front-end application.
- npm run dev
  
  This command runs the front-end application as a web application.
The front-end application will start running at http://localhost:5173/.
Access the front-end application via http://localhost:5173/.
Click Login, and sign in with the credentials of a user that you created in Asgardeo.
To allow your application to access your Choreo account, select the User Account checkbox and click Allow.

The application opens as follows.
Add three new reading items with different statuses.

For example, the details can be as follows:

Title Author Status

The Museum of Innocence Orhan Pamuk reading

The Remains of the Day Kazuo Ishiguro to_read

David Copperfield Charles Dickens read

To add each record, follow the steps given below:
1. Click + Add New.
2. Enter values for the Name, Author, and Status fields.
3. Click Save.
Three tabs open for each status. To delete a reading list item, you can click Delete.

To verify whether the reading list is personalized for each user, you can sign in as a different user. The reading list items you entered above will not appear for the other user.

Congratulations! You have successfully exposed a service endpoint as a REST API via Choreo and securely consumed the API from a web application.

Field	Value
Name	`Reading List Service`
Description	`Manages reading lists`

Parameter	Value
author	`Bram Stoker`
status	`to_read`
title	`Dracula`

Title	Author	Status
`The Museum of Innocence`	`Orhan Pamuk`	`reading`
`The Remains of the Day`	`Kazuo Ishiguro`	`to_read`
`David Copperfield`	`Charles Dickens`	`read`