How to Work With Internal APIs

  • By Menaka Jayawardena
  • 28 Jul, 2022

Photo by Sam Balye on Unsplash

Internal APIs are REST APIs developed and deployed in Choreo, that are not exposed to end users over the internet. These APIs can only be accessed from another API deployed in Choreo and are deployed as fully managed APIs providing the full spectrum of API management capabilities such as lifecycle management, observability, throttling and security. To learn more about them, read this blog.

In this tutorial we will be creating a simple order processing service, which handles customer orders. The order processing service needs to update the stock through the inventory management service. We will also learn how to test and consume the internal API we created. Let’s begin.

1. Creating an Internal API

1. Login into the Choreo Console.

2. Create a new project.

3. Click on Rest API, and then click on Create an API from Scratch to create it.

Figure 1: Creating an API from Scratch

4. In the dialog box, provide the API name (InventoryLocatorAPI) and description. 

5. From the Access mode dropdown list, select Internal and click Next. This is shown in Figure 2.

Figure 2: Selecting Access Mode

6. Select the desired method you wish to use the source repository and click Create

7. Once the API is created, implement the required functionality via the low-code editor or pro-code editor, push the changes and deploy the API. This is shown in Figure 3.

Figure 3: Deployed API

2. Testing an Internal API

Since internal APIs are not accessible outside Choreo, once the API is deployed, it can only be invoked from another Choreo component. The API can be tested by invoking an internal API via cURL from Choreo’s low-code editor. Let’s begin.

1. Navigate to the Develop view of the API and click on Edit Code to open the low-code editor.

2. In the Choreo Console, navigate to the Test view of the API.

3. Copy the cURL command from the test view (provide any parameters required to generate the correct cURL command). This is illustrated in Figure 4.

Figure 4: cURL view

4. Navigate to the low-code editor and open the terminal as shown in Figure 5. Afterwards, paste the copied cURL command, and try out the API as shown in Figure 6.

Figure 5: Opening terminal in Choreo low code editor

Figure 6: Testing the internal API via Choreo Low Code Editor terminal

5. After the tests are completed in the development environment, navigate to the Deploy tab and click on Promote in the development card to promote the API to the production environment. 

3. Consuming an Internal API

Internal APIs can be consumed similar to an external API. The difference is that it is not accessible outside Choreo. Therefore, it should be consumed from another REST API created in Choreo. 

An internal API can be consumed by:

1. Invoking the API via an http client.

Create an http:Client instance with the internal API endpoint and generate an access token. This is the straightforward way to invoke the API, but you must provide an option to refresh the token when it expires.

2. Using the connector published for the internal API.

This is the most effective method to use an internal API. Choreo connectors can handle access tokens (generating, refreshing etc.). This allows developers to focus more on the business logic as other details are taken care of. 

In both cases, the API must be published and a suitable subscription must be created. To publish the API:

1. Navigate to the Manage -> Lifecycle page of the internal API and click Publish.

2. As shown in Figure 7, when prompted to publish the connector, click Yes Please and Publish Connector from the confirmation dialog box.

Figure 7: Deploy Connector

Note: This is required if the API needs to be consumed using the connector, otherwise you can select not to publish the connector. 

To subscribe and get an access token for the API:

1. As shown in Figure 8, click the Go to Devportal button to visit the Choreo developer portal. 

Figure 8: Go to Developer portal

2. Click on the Applications tab.

3. Click on Create an Application. In the resulting dialog box, provide the application name and click Create.

4. In the application view, click on the Subscriptions menu from the left panel and click on Add APIs. This is shown in Figure 9.

Figure 9: Add APIs

5. Select the InventoryLocatorAPI and click Add as shown in Figure 10.

Figure 10: Adding API Subscription

6. Navigate to the Application Keys page by clicking on Production Keys -> OAuth2 tokens from the left menu.

7. As shown in Figure 11, click Generate Credentials to generate the consumer key and secret. You can also generate an access token by clicking Generate Test Token. Copy the access token and keep it secure. This is shown by Figure 12.

Figure 11: Generate Credentials

Figure 12: Generating test token

3.1 Consuming the Internal API Using an http:Client

1. Log into the Choreo Console and create a new Rest API from Scratch. Afterwards, use these details.
Name: OrderProcessingAPI
AccessMode: External

2. In the Develop page, Click Edit Code, and go to the low-code view.

3. In the low-code view, click the + button in the diagram and select HTTP. This is seen in Figure 13.

Figure 13: Creating HTTP Client

4. In the right panel, provide a name for the client as well as the endpoint URL, and click Continue to invoke API. This is shown by Figure 14.

Figure 14: Providing HTTP Client endpoint

5. Select the HTTP operation and provide the resource path. Next, as shown in Figure 15, provide the access token when we generated the test token.

Figure 15: Providing Http Client operation and parameters

6. Click on Save and Done to add the Http client configuration. 

3.2 Consuming the Internal API Using a Connector

1. In the Develop page, click Edit Code and go to the low-code view.

2. In the low-code view, click on the + button in the diagram and select Connector. This is shown by Figure 16.

Figure 16: Creating Connector instance

3. From the connector’s listing view, search for the InventoryLocator connector and select it as seen in Figure 17.

Figure 17: Selecting InventoryLocator connector from the connector listing

4. Provide a name for the connector and provide the client ID and secret generated for the InventoryLocator API in Step 7. This can be converted to configurable values so the real values do not need to be hardcoded and can be provided at deployment. This is shown in Figure 18.

Figure 18: Providing connector parameters

5. Then, click on Save and Continue

6. Select the operation that needs to be invoked. Provide the requested parameters and Click on Save. This is shown in Figure 19.

Figure 19: Selecting Connector operation 

After adding the connector or the http:Client, complete the implementation by adding more functionalities. The API can be tested at development by clicking on the Run and Try it buttons. A built in swagger console will be opened to test the API before deploying it. This is illustrated in Figure 20.

Figure 20: Testing the API in Choreo Low Code view

After completing the development, commit and push the changes before deploying the API.

Testing the Order Processing API

We have implemented and deployed the order processing API. To test its functionality, navigate to the Deploy page and click Order Processing API to deploy it.

If you have provided the client ID and secret as configurables, a window will appear to enter the values.

Once deployed, navigate to the Test page of the order processing API. Since it's an external API, it can be tested like a Rest API using the built in Swagger UI of Choreo Console.

By leveraging internal APIs, we can implement more comprehensive and complex business functionalities without exposing APIs unnecessarily to the user. 

Congratulations, you have successfully created, consumed, and tested an Internal API!

To learn more about Choreo, check the official Choreo documentation, including our Quick Start Guide.

Table of Contents