How-tos

Where should I put API Connect?

Share this post:

Let’s say you need an API management solution and you’ve decided to give API Connect a try. You found API Connect in the Bluemix catalog (under Services then APIs). You’re just about to hit the Create button for the Essentials plan (50,000 free calls a month!) when you realize something: you’re not sure which Bluemix space to use.

Let us explain.

Each Bluemix organization is divided into spaces. You deploy your applications in these spaces—and you provision services such as databases, Watson services, and API Connect in these spaces as well. Members of a space have access to the apps and services in the space. One typical pattern for organizing them is to create a space for each environment in your development lifecycle—for example, you might have “dev,” “qa,” and “production” spaces.

Within API Connect, you create catalogs for each environment and publish your APIs to each catalog as the APIs move through the development lifecycle. API consumers can browse a catalog at an associated portal which is assigned a URL. It is important to note that where the API Connect Gateway and developer portals are running is not related to any Bluemix space—and API Catalog names need not match names with any Bluemix space.

If API Connect catalogs and portals are independent of Bluemix organizations and spaces, where does API Connect fit into your Bluemix structure? Should you provision an instance of API Connect to each Bluemix space in your lifecycle?

I recommend creating a separate space called ‘API’ with a single instance of API Connect.

Deploying microservices on Bluemix

Your API Connect APIs might proxy to target microservices that are running in Bluemix, on-premises or in another cloud. Let’s take a greenfield project as an example and imagine that you are developing new microservices that externalize access to new or existing data. Your team develops those microservices and deploys them to Bluemix. You are using a toolchain with a development pipeline to push those applications through your dev, qa and production Bluemix spaces.

This diagram shows how you could organize your Bluemix spaces if you have one microservice, following the naming convention described in this post:

API Connect

Important API Connect endpoints in Bluemix

API Connect endpoints follow this pattern by default:

  • Portal URL – where application developers go to browse and subscribe to APIs published to a catalog:
    https://<catalog>-<bluemix_org>-<bluemix_space>-<apic-host>
  • API Base URL – Base URL for all APIs published to a catalog:
    https://<apic_host>\<bluemix_org>-<bluemix_space>/<catalog>

This table shows a concrete example of the URLs in a deployment where API Connect is provisioned to the U.S. South region in a Bluemix Organization named “acme” and a Bluemix Space named: “api”. The API Product is deployed to three catalogs: Stock Services Dev, Stock Services QA, and Stock Services.

Screen Shot 2017-01-17 at 12.32.33 PM

Notice that there’s no portal URL for the “Stock Services Dev” catalog. You can optionally create a Portal for any catalog, but during the development cycle, you may simply want to test the endpoints and not the Portal experience. API Connect gives you test credentials (client ID and client secret) to test API Products that you publish to a ‘development mode’ (i.e., sandbox) catalog.

Governance of the API lifecycle

You can now create more microservices and APIs and publish these to your existing catalogs or create new ones. Let’s take a closer look at some of the details of your setup in this single instance of API Connect. Specifically, we will look at:

  1. How your configuration targets microservices
  2. How you can use API Connect Spaces to isolate API teams
  3. How you can govern the API Product Lifecycle

Parameterizing microservice target endpoints

What if your target microservices are not running on Bluemix? Your target microservices may be private or in another cloud and not in any Bluemix space. In this case, it still is appropriate to use a space such as ‘api’ in which you provision API Connect and use the same principles. The target microservices—whether on Bluemix or running elsewhere—can be parameterized by catalog so that when the API is published to a catalog, the matching target endpoint is automatically substituted. For more information on configuring API Properties to parameterize by catalog, see the Knowledge Center.

API Connect spaces are different from Bluemix spaces

You may have multiple teams responsible for different APIs. API Connect has a ‘Spaces’ feature in its catalog settings that allows partitioning of a catalog. This enables independent teams to govern the APIs for which they are responsible for publishing to a common catalog. Catalog spaces should not be confused with Bluemix spaces – they both provide logical separation for different teams, but one applies to Bluemix Organizations and the other applies to the API Products published to an API Connect catalog. If you have multiple teams developing microservices in Bluemix, you might qualify your Bluemix space names as follows (or some variation of this):

team1_dev, team1_qa, team2_prod, team2_dev, team2_qa, team3_prod

Teams can independently manage and publish the APIs that externalize these microservices to shared API Connect catalogs.

Managing access and authorization for catalogs

You may need to set some governance controls on publishing APIs to certain catalogs, especially Production. API Connect provides two mechanisms for this:

  1. Approval settings for Product Lifecycle
  2. Role-based controls for viewing and performing actions in an API Connect catalog and space

Approval settings for the product lifecycle

Select your catalog. Navigate to Settings then Approvals. This screenshot shows the configuration for a catalog named “Production”:

Screen Shot 2017-01-17 at 10.43.18 AM

This configuration enforces an approval process for all Product Lifecycle operations except staging. When the operation is called, API Connect sends an approval notice to all members of the catalog that are authorized to approve. Approvers can view the list of pending approvals in the Approvals tab for the catalog. By setting approvals, you can ensure that deployments to certain catalogs or spaces are gated by an approval step.

Role-based controls

An API Connect administrator can add new members at three levels:

  1. Top-level API Connect instance
  2. Catalog
  3. Catalog space (if spaces are enabled for a catalog)

There are role definitions for the API Connect instance and for each catalog and space (if applicable). In this image, you see the default role settings. Notice how an API Developer in the Production catalog is not authorized to manage products. An API Developer is limited to viewing analytics data and application subscriptions:

Screen Shot 2017-01-17 at 11.38.03 AM

You can also manage the membership. Below you see the members and their roles for the Product catalog. This allows you to have a more restricted membership in the Production catalog than you do in your Dev or QA catalogs.

Screen Shot 2017-01-17 at 11.40.10 AM

Here are more details on catalog and space membership and roles.

Key takeaways

To summarize:

  1. Typically, you only need a single instance of API Connect per Bluemix organization. This API Connect instance is provisioned to a Bluemix space, often called ‘api’.
  2. An API Connect instance can be used to publish APIs from one or more teams to one or more API Connect catalogs.
  3. If multiple teams are publishing to a common catalog, those teams can be isolated from each other by using API Connect catalog spaces.
  4. You can use the Roles and Membership setting to control who has authorization to view and manage different steps and environments of the API and Product lifecycle.
  5. The target microservices externalized by your APIs can be running anywhere that API Connect has access. Application developers will visit API Connect Developer Portals to browse and subscribe to APIs.

Senior Technical Staff Member (STSM), Architect Practice Lead, Americas, IBM Cloud Garage

More How-tos stories
May 1, 2019

What’s Included in the IBM Cloud Developer Tools Version 2.2.0

I’m pleased to announce the latest version of IBM Cloud Developer Tools CLI, which contains some exciting new features.

Continue reading

April 26, 2019

Help Shape the Future of Cloud Foundry

Are you a Cloud Foundry user? If so, here's your opportunity to influence the future of Cloud Foundry with the 2019 user survey.

Continue reading

April 25, 2019

Develop in Public Cloud, Deploy Anywhere with IBM Cloud DevOps

In this article, we explore how to deploy multicloud apps developed with IBM Cloud Continuous Delivery to a network-accessible IBM Cloud Private installation.

Continue reading