January 25, 2017 | Written by: Ilene Seelemann
Categorized: DevOps | How-tos
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:
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:
- API Base URL – Base URL for all APIs published to a 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.
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:
- How your configuration targets microservices
- How you can use API Connect Spaces to isolate API teams
- 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:
- Approval settings for Product Lifecycle
- 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”:
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.
An API Connect administrator can add new members at three levels:
- Top-level API Connect instance
- 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:
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.
Here are more details on catalog and space membership and roles.
- 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’.
- An API Connect instance can be used to publish APIs from one or more teams to one or more API Connect catalogs.
- If multiple teams are publishing to a common catalog, those teams can be isolated from each other by using API Connect catalog spaces.
- 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.
- 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.