Develop an API Proxy from a GitHub Repository Source

An API proxy acts as an intermediary between an existing API and Choreo, intercepting all requests made to the API. It also functions as a managed API, allowing you to apply essential API management features such as security policies and rate limiting.

In this guide, you will:

• Create an API proxy component to expose an existing API.
• Deploy the API proxy.
• Test the API proxy to verify its functionality.
• Manage the API.
• Consume the API.

Prerequisites

1. If you're signing in to the Choreo Console for the first time, create an organization:

   1. Go to https://console.choreo.dev/ and sign in using your preferred method.
   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.

2. Fork the Choreo samples repository, which contains the sample proxy source.

Step 1: Create an API proxy

You can create an API proxy either by selecting the source from a GitHub repository, uploading an OpenAPI specification file, or providing an OpenAPI specification URL. This guide demonstrates how to create an API proxy using a GitHub repository as the source.

1. Go to https://console.choreo.dev/ and sign in. This opens the project home page.
2. If you already have one or more components in your project, click + Create. Otherwise, proceed to the next step.

3. Click the API Proxy card. This opens the Create an API Proxy pane.

4. Click on Authorize With GitHub card under Connect a Git Repository section to connect your GitHub account.

   • If you haven’t connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you forked in the prerequisites section to install the Choreo GitHub App.

   Note

   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 needed. Write access is only used for sending pull requests; Choreo will not push changes directly to your repository.

5. Enter the following repository details:

   Field	Value
   Organization	Your GitHub account
   Repository	choreo-samples
   Branch	main
   API Directory	/department-api-proxy-from-github

   Note

   To select the relevant directory, click on the Edit action next to the API Directory input field. Then, enter department-api-proxy-from-github as the directory name to quickly search and locate the correct directory.

6. Specify the following values as Proxy Metadata:

   Info

   The Context field must be unique and cannot be changed after creation.Version and Target are mandatory fields. Target can be changed at any time after the creation.

   Field	Value
   Context	department-service
   Version	v1.0
   Target	https://samples.choreoapps.dev/company/hr

7. Specify the following values as Component Details:

   Info

   The Component Name field must be unique and cannot be changed after creation. This value is automatically generated, but you can edit it if necessary. Component Display Name is a required field.

   Field	Value
   Component Display Name	Department Service
   Component Name	department-service
   Description	This is a sample proxy for department service

8. Click Create. This creates the API proxy component and takes you to the Build page.

Note

When you create an API proxy from a GitHub repository source, the GitHub source serves as the single source of truth. Therefore, any modifications, such as adding or deleting resources, must be made through the GitHub repository.

Step 2: Build

Info

The initial build starts automatically when you create the API proxy, and you will be redirected to the Build page. In this case, you can skip the steps below. If you need to manually trigger a build later, follow these steps.

1. On the project home page, click on the Department Service component you created. This takes you to the component overview page.
2. In the left navigation menu, click Build.
3. On the Build page, click Build Latest.

Note

The build process may take some time. You can track progress in the Build Details pane. Once complete, the build status changes to Success.

Step 3: Deploy the API proxy

1. In the left navigation menu, click Deploy.
2. In the Build Area card, click Configure & Deploy. This opens the Configure & Deploy pane.
3. Select External as the API Access Mode and click Deploy. The Development card indicates the Deployment Status as Active when the API proxy is successfully deployed.

Now you are ready to test the API proxy.

Step 4: Test the API proxy

Choreo allows you to test your API proxy using either the integrated OpenAPI Console or cURL. In this guide, you will use the OpenAPI Console.

Tip

Choreo enables OAuth 2.0 to secure APIs by default. Therefore, you need an access token to invoke an API.

• Choreo automatically generates a key to test the API via the OpenAPI Console. To view the key, click the show key icon in the Security Header field.
• To disable security for the entire API or a specific resource:
  1. In the left navigation menu, click Deploy.
  2. Go to the Build Area card and click Security Settings.
  3. In the Security Settings pane:
     • To disable security for the entire API, clear the OAuth2 checkbox.
     • To disable security for a specific resource, expand the relevant resource and turn off the Security toggle.
  4. Click Apply.
  5. Then click Deploy.

1. In the left navigation menu, click Test and then click OpenAPI Console.
2. Select Development from the environment drop-down list.
3. Expand the GET /department/{departmentId} resource and click Try it Out.

4. Enter 1 as the departmentId and click Execute. You will see a response similar to the following:

   

   This indicates that your API proxy is working as expected.

Step 5: Manage the API proxy

Now that you have a tested API proxy, you can publish it and make it available for application developers to consume. In this guide, you will apply rate limiting to the API and publish it.

Step 5.1: Apply rate limiting to the API proxy

1. In the left navigation menu, click Deploy.
2. Go to the required environment card and click the settings icon corresponding to API Configuration.
3. In the CORS, Rate Limiting and Resiliency pane, click Rate Limiting to expand the section.
4. Select API Level as the Rate Limiting Level.
5. Specify appropriate values for the Request Limit and Time Unit fields. You can proceed with the default values.
6. Click Apply. This applies the rate limiting level to the API proxy and redeploys it.

Step 5.2: Publish the API proxy

Publishing makes your API available in the Choreo Developer Portal, enabling application developers to access and use it.

1. In the left navigation menu, click Lifecycle under Manage. This takes you to the Lifecycle page.
2. Click Publish.
3. In the Publish API dialog, click Confirm to proceed with publishing the API. If you want to change the display name, make the necessary changes and then click Confirm. This changes the API lifecycle state to Published.

Step 6: Invoke the API From DevPortal

To generate credentials for the published API and invoke it via the Choreo Developer Portal, follow these steps:

1. In the Lifecycle page, click Go to Devportal. This takes you to the Department Service in the Choreo Developer Portal.

2. Invoke the API:

   1. In the Developer Portal left navigation menu, click Try Out.
   2. In the Endpoint list, select Development as the environment to try out the API.
   3. Click Get Test Key to generate an access token.
   4. Expand the GET /department/{departmentId} resource and click Try it out.

   5. Enter 1 as the departmentId and click Execute. You will see a response similar to the following:

      

Now, you have gained hands-on experience creating, deploying, testing, and publishing an API proxy using Choreo.