Think 2021: New tools have the developer ecosystem and IBM building together Learn more

Managing your APIs throughout the API lifecycle

IBM API Connect for IBM Cloud is an integrated API management offering, where all of the steps in the API lifecycle include creating, running, managing, and securing APIs are performed. With the API Connect service, you can easily serve your APIs over a secure developer platform. API Connect allows developers to focus on APIs while it does the rest of the work.

Prerequisites

Estimated time

Completing this tutorial should take about 45 minutes.

Steps

Step 1. Deploy your service on IBM Cloud

Services can be implemented by using any programming language, such as Java, Node.js, JavaScript, PHP, Ruby, or Python. In this tutorial, we will create an API by deploying a service that was built using Node.js.

You can deploy your service in multiple ways on IBM Cloud. In this tutorial, we show you how to deploy your service using the Cloud Foundry runtime and using the Kubernetes Service on IBM Cloud.

Deploy your service on IBM Cloud using Cloud Foundry runtimes

  1. Log in to your IBM Cloud account.

  2. From the Navigation menu, select Cloud Foundry > Overview.

  3. Scroll down the page, and in the Application Runtimes section, choose your runtime. For this tutorial, we chose the .js runtime (SDK for Node.js).

  4. On the service creation page, provide the required details, and click the Create button.

    The service will be created and you can access it by clicking the Visit App URL link.

Alternatively, if you have your application code, you can install and use the Cloud Foundry commands to push your application (service) using the following commands.

  $ ibmcloud login        ## Login to IBM Cloud
  $ ibmcloud target --cf  ## Set the target Cloud Foundry org and space
  $ ibmcloud cf push      ## Push the application to IBM Cloud

Note the application URL. It will work as the endpoint of your service and will be used in API Connect.

Deploy your service using IBM Kubernetes Service on IBM Cloud

To deploy your service on a Kubernetes Cluster, follow the steps in the IBM Cloud Kubernetes Service workshop:

  1. Install the CLIs and plugins in the Lab 0 setup.

  2. Create and deploy your application following the steps in the Lab 1 instructions.

After successful deployment of your service on Kubernetes, it will be accessible at:

  http://<public-ip-of-kubernetes-cluster>:<port>/

This URL will work as the endpoint of your service and will be used in API Connect.

Step 2. Manage your APIs using IBM API Connect

IBM API Connect on IBM Cloud provides a unified user experience across the API lifecycle and helps you to create and manage your APIs with business-level controls by setting different levels of security and visibility while sharing APIs with application developers. (You can also use IBM API Connect that is included in IBM Cloud Pak for Integration to manage your APIs.)

The following diagram shows the workflow steps that needs to be completed before sharing the APIs.

workflow-steps

After pushing the API to IBM Cloud, you can control usage, increase adoption and track statistics of APIs. The first two steps of the workflow was covered in Step 1. This section will help you to understand how to perform the further steps of workflow with API Connect. Let’s start.

First, create the API Connect service instance, if it is not yet created.

On the IBM Cloud Dashboard, in the Cloud Foundry Services list, click the API Connect service instance. The API Connect dashboard is displayed.

dashboard

The API Connect dashboard shows the default provided Sandbox catalog. In this tutorial, we will use the sandbox catalog for serving our API but you can also create your own catalog.

Identify the end point URL in API Connect

  1. On the API Connect Dashboard, click the Sandbox catalog.
  2. Click Settings.
  3. Click Gateways.

Note the Endpoint URL for your service.

endpoint-url

Add the API in API Connect

  1. Click the Dashboard tab.

  2. From the >> button next to the Home icon, click Drafts.

  3. Click the APIs tab.

  4. Select Add > New API.

    APIs tab in API Connect

  5. Provide the required details of your API.

    alt

    Expand the Additional Properties and select None under the Security section.

    alt

    In some scenarios where cross-domain requests are not allowed at the service side, you can disable CORS too.

    Note: The other options available for security are Client ID and Client ID and Secret. If you choose the Client ID option, then you need to create an API key security definition to specify a credentials requirement. If you choose the Client ID and Secret option, you must create two API key security definitions, one for each type of credentials. For more details, see the API Connect documentation.

  6. Click Create API. The API will be listed on the Drafts page.

  7. Click on your API, and go to Paths section.

    API Draft, paths section

  8. Add a path. It gets added as /path-1 for the service. Save the API.

    API Path, save icon highlighted

Bind the service to the API

  1. Click the Assemble tab.

  2. Click the invoke node.

  3. In the panel that opens on the right side of the screen, provide the following information and then save the API:

    • Provide your service URL.
    • Provide the HTTP method for your service. In this tutorial, it is GET.
    • Choose a value for the cache type. In this tutorial, we used No cache.
    • Use the default values for the other optional parameters.

    Screen shot of invoke node

  4. Click the Design tab. Save the API, and validate the API design which is placed near Save button.

Add a product in API Connect

You create a product to collect a set of APIs into one offering that you can make available to other developers.

  1. Go back to the Drafts page.

  2. Click the Products tab. Then, click Add > New Product.

    Add new product window

  3. Specify the title, name, and version click Create product.

  4. Click on your product. Go to the APIs section.

    APIs section

  5. Click the Add API button which is in the upper right of the APIs section. Select your API from the saved APIs, which you want to bind with this product, and click Apply.

  6. Click the Save button.

  7. Click the Stage button which is next to the Save button. Select the Sandbox catalog.

    Staging the product

    On the Catalog Dashboard, the product will be displayed in the Staged state.

Publish the product on IBM Cloud

After staging the product, you need to publish it.

  1. From the >> button next to the Home icon, select the Dashboard and click Sandbox catalog.

  2. Select the staged product and publish it using the three dots menu to the right.

The possible lifecycle states for a product version are staged, published, deprecated, retired and archived. The product management operations move a product version from one lifecycle state to another; for example, the Retire operation moves a product version from the published to the retired state.

Test the API in API Connect

  1. From the >> button next to the Home icon, click Drafts > APIs.

  2. Click your API, and then click the Assemble tab.

  3. Click the play button next to the Search bar.

    Assemble tab

  4. In the Test panel in the left side of the screen, verify the information in the Setup section. If the product name that is displayed in this section is not the one that you want to test, then click Change Setup and select the correct catalog and product name to test. Click Next.

  5. In the Operation section, select your path in the drop-down, and click Invoke.

    Operations section

  6. In the Response section, you’ll see the status code and response time, similar to this screen shot:

    Response section

    Status code 200 means that it has successfully invoked the service.

    Sometimes you might get the response with status code as -1 with the message “Causes include a lack of CORS support on the target server.”” The CORS error should go away if CORS is enabled on the server (service) and API Connect.

Share the API Target URL

After the testing of the API is successful, you can share the API target URL of the service with other developers.

The API target URL of the service will follow this format:

https://<Endpoint URL of your API Connect>/<api name>/<path added>

For example, the API target URL for my service is this:

https://api.us-south.apiconnect.appdomain.cloud/xxxx/sb/cfapi/path-1

Summary and next steps

You can now connect a lot of services to your API Connect platform. In this tutorial, we just created one service, bound it to API Connect, tested it, and accessed it through API connect without exposing its actual endpoint.

As a next step, you should try out securing your APIs through API Connect. You can learn how to secure the APIs using OAuth 2.0 in this tutorial.