Exercise: Create and publish a managed API endpoint for an existing REST service, using API Connect

As you build your server applications with REST interfaces, you need to consider how these interfaces are exposed to other developers. While it is technically possible to simply give them a direct URL to the component in question, typically you will want to take a much more managed approach to formally publishing a URL endpoint. For instance, you need to consider:

  • How can you horizontally scale the resources running your API endpoint?

  • How can you monitor and manage the endpoint?

  • How will you enable transition to new versions of your API, deprecating old versions over time

  • How can you secure the traffic to the endpoint?

While you could implement the above directly in your service along with your code, it is good practice to separate the above functionality - particularly if you have multiple services. Having a standard way of implementing the above will bring consistency to the experience received by developers using your API. This is the goal of the API Connect component of Cloud Pak for Integration.

In this exercise, we will show you how to use API Connect to accomplish some of above, by creating and publishing a new, managed API endpoint for the REST service you built with App Connect in the previous exercise

When you have completed this exercise, you will understand how to

  • Created a managed API endpoint, by importing an OpenAPI definition for an existing REST service.

  • Publish the new API endpoint

  • Tested the API in the API Connect developer toolkit.

Steps

All the steps below are carried out on the desktop Linux OS VM.

  1. Summary

1. Describe the API for which you want to create a managed endpoint, by importing an OpenAPI specification

In the previous exercise you created a REST service for synchronizing data with Salesforce. This is the service for which you are going to build a new, managed API endpoint. The first thing you need to do is import, into API Connect, the OpenAPI definition for the API you created as part of this service. By deafult, this will become both the external API structure you publish, as well as the service API the managed endpoint will call to satisfy requests it receives.

To obtain the OpenAPI specification for your existing REST service, in the App Connect Dashboard click on the tile for your existing server:

Running server

Click on the API tile to see the details of the flow's API

API tile

You should see the details of your flow's API. In your your browser, right click on the OpenAPI document link and select Save Link As ... from the context menu (alternatively you can click on the link and select Save from the menu bar).

Now you can import this into API Connect as the API for your new managed endpoint to call. In a new browser tab open the Cloud Pak for Integration tab and under View Instances click on the link for API Connect.

Launch API Connect

You may be asked to log into API Connect, in which case you should select to log in using the IBM Common Services user registry.

Once loaded, click on the Develop APIs and Products tile

Develop APIs and Products tile

Click ADD->API

Add API

On the next screen select From Existing OpenAPI Service under Create and then click Next.

Existing OpenAPI

Now choose user001sf.json from your local file system and click Next.

Choose file

Choose the default values in the next few panels. You will notice that by default your API will have security added to it (which will be terminated at your endpoint), helping to secure calls that will then be re-directed to your REST service running in App Connect. You'll reach the Summary panel and the API should be imported successfully as shown below. Click Edit API.

Edit API

NOTE: Importing an OpenAPI specification is just one of the generic ways you can define an API in API Connect. It enables you to build a managed endpoint for your REST service however it was created - which is why this method is used in this workshop. As an aside, there is an alternative method, if the service was created in App Connect. You can push an API defintion direct from App Connect to API Connect (without having to save off the OpenAPI specification) - using the Share REST APIs option in the ... menu from the appropriate flow item in the App Connect Dashboard.

2. Configure the API

After importing the API you'll be given an opporunity to add or modify existing properties

API Overview

Click Save to complete the configuration.

3. Test the API

In the API designer, you have the ability to test the API immediately after creation in the Assemble view.

On the top Navigation, click Assemble.

Assemble

Click Invoke in the flow designer. Note the window on the right with the configuration. It calls the target-url with the same request path sent to the API Connect endpoint. Ensure the URL is set to $(target-url)$(request.path).

Invoke target

Click the play icon as indicated in the image below.

Play icon

Click Activate API to publish the API to the gateway for testing.

Activate API

After the API is published, find the Operation field and choose post /Client. Note that your Client ID is prefilled for you.

Choose a POST operation

Choose to Generate data for a request and REMOVE the Client ID. Scroll all the way to the bottom of the browser window and click Invoke.

Invoke API

If this is the first test of the API, you may see a certificate exception. Simply click on the URL and choose the option to proceed.

Go back to the test view and click Invoke again.

Now you should see a Response section with status code 201 Created and the body displaying the new Salesforce client ID.

Return from API call

Summary

Congratulations! You successfully completed this part of the lab!