The API Connect REST APIs

How to get started with the API Connect REST APIs

The API Connect REST APIs can be used for the following actions:

Automate the administration of API Connect.
Implement scripts and tools to support a continuous integration environment for API development and publishing.
Manage catalogs of APIs, and their subscribers.
View analytics data.

Complete reference documentation for the API Connect REST APIs is available here: API Connect REST API documentation.

Prerequisites

To use the API Connect REST APIs, you must meet the following prerequisites:

Have an API Connect user that is a member of a provider or consumer organization. To call APIs that are cloud scoped, your user must be a member of the admin organization, see Adding members to the admin organization.
App credentials: A client_id and client_secret. These credentials can be obtained from the API Manager or Cloud Manager UI, or provided to you by your API Connect administrator.

To get the API endpoint URLs and the app credentials, follow these steps:

In the API Manager UI home page, click the Download toolkit tile.
Download the Toolkit credentials (you do not need to download the CLI or API Designer).

Open the downloaded credentials.json file to see the platform and consumer endpoints, and the credentials to call APIs on these endpoints:

{
  "cloud_id": "e8fcdec3-bfb9-44bd-bf90-03d8639c4916",
  "toolkit": {
    "endpoint": "https://example-platform-api.ibm.com/api",
    "client_id": "7ad7b6c5-fa07-4222-808d-8de7266dcd1a",
    "client_secret": "b7127e44-4811-48be-be9d-6591302de04a"
  },
  "consumer_toolkit": {
    "endpoint": "https://example-consumser-api.ibm.com/consumer-api",
    "client_id": "3b10e0db-1cd4-4aa8-af02-51a83e334f1c",
    "client_secret": "a5a672b7-e3b2-4d2b-984b-4059ea82ae65"
  },
  "governance": {
    "endpoint": "https://example-governance.ibm.com/governance",
    "client_id": "ba48537c-7a6e-4232-92b6-ae67ad764933",
    "client_secret": "790d8a6d-e323-46bd-a05c-3d212e93d794"
  },
  "discovery": {
    "endpoint": "https://example-discovery.ibm.com/discovery",
    "client_id": "d872a2f4-bc6e-4e91-b187-bbb5b99d4605",
    "client_secret": "c0b5ddf9-58e6-4246-88de-243ce217731a"
  }
}

The endpoints and credentials that are contained in the credentials.json file are

toolkit: The platform API endpoint. Use this for provider organization scoped and cloud scoped API calls.
consumer_toolkit: The consumer API endpoint. Use this for consumer organization scoped API calls, such as creating an app in a consumer organization.
governance: See the API Governance feature.
discovery: See the API Discovery feature.

Note: Your API Connect cloud administrator might provide you with different app credentials to use. In this case, do not use the credentials that are in the credentials.json file.

Generating app credentials

If you are the cloud administrator, you can create separate app credentials for each user with the toolkit CLI. Follow these steps:

Create a JSON file that contains the new credentials:
```
{
  "name": "User1App",
  "client_id": "User1ID", 
  "client_secret": "User1Secret",
  "client_type": "<toolkit or consumer_toolkit>"
}
```
Where client_type is set to toolkit for creating credentials for provider organization members, and set to consumer_toolkit for consumer organization members.
Use the toolkit CLI to register the credentials:
1. Log in as a cloud admin user:
```
apic login --server <platform api endpoint> --username <username> --realm <realm>
```
2. Register the new credentials:
```
apic registrations:create --format json --server <platform API endpoint>  <JSON credentials file>
```
If you do not have the toolkit CLI installed, then refer to Setting up the API Connect toolkit.

Obtaining a bearer token

Each call to the REST APIs must be authenticated with a bearer token in the HTTP Authorization header. Use your app credentials to obtain a bearer token.

Request your bearer token with the following REST call:

curl -k -X POST -d '{"username": "<username>", "password": "<password>", "realm": "<realm>", "client_id": "<client_id>", "client_secret": "<client_secret>", "grant_type": "password"}' -H 'Content-Type: application/json' https://<platform api endpoint>/token

Where:

<username> is the API Connect user that you want to make the REST API calls. The user must have the scope and permissions for the API calls that you want to make:
- Provider organization members can call make API calls at organization scope, such as publishing products or viewing analytics data for the provider organization.
- Consumer organization members can make API calls only at catalog and space scope, such as subscribing an app to a published product within a catalog.
- Cloud administrators can make API calls at cloud scope, such as creating new provider organizations or registering gateway services.
<password> is the password for the specified <username>.
<realm> is the user registry realm for the specified <username>.
The default realms are:
- provider/default-idp-2 for provider organization members.
- consumer:<provider org>:<catalog>/<catalog>-idp for consumer organization members.
- admin/default-idp-1 for cloud administrators.
To view the available provider organization realms, you can run the following REST API call without any authentication:
```
curl -k -X GET --url 'https://<platform api endpoint>/api/cloud/provider/identity-providers'
```
To view consumer organization realms, run:
```
curl -k -X GET --url 'https://<consumer api endpoint>/consumer-api/consumer/identity-providers' -H 'X-IBM-Consumer-Context: <provider org>.<catalog>'
```
To view cloud admin realms:
```
curl -k -X GET --url 'https://<platform api endpoint>/api/cloud/admin/identity-providers'
```
<client_id> is the client ID from the credentials.json file, or as provided by your API Connect cloud administrator.

Provider organization members and cloud administrators should use the ID from the toolkit section of the credentials.json file to make calls to the platform API.

Consumer organization members should use the ID from the consumer_toolkit section of the credentials.json file to make calls to the consumer API.
<client_secret> is the client secret from the credentials.json file, or as provided by your API Connect cloud administrator.
<platform api endpoint> is the platform API endpoint from the "toolkit" section of the credentials.json file, or as provided by your API Connect cloud administrator.

The bearer token is returned in the access_token property:

{
    "access_token": "<bearer_token>",
    "token_type": "Bearer",
    "expires_in": 28800
}

Note: The expires_in value is the number of seconds before the token expires. After expiry, you must request a new bearer token.

Making REST API calls

Use your bearer token when you make calls to the REST API:

curl -k -X <HTTP Method> --url 'https://<rest api endpoint>/<api path> -H 'Authorization: Bearer <bearer_token>'

If you make calls to the consumer API, then you must include an extra header that specifies the provider organization and catalog:

-H 'X-IBM-Consumer-Context: <provider org>.<catalog>'

Example REST API calls

Get a list of the provider organizations

User a bearer token that was created with provider organization member credentials, and specify the platform API endpoint:

curl -k -X GET --url 'https://<platform api endpoint>/api/orgs' -H 'Authorization: Bearer <bearer_token>'

Get a list of the apps in a catalog

Use a bearer token that was created with consumer organization member credentials, specify the consumer API endpoint, and include the X-IBM-Consumer-Context header:

curl -k -X GET --url 'https://<consumer api endpoint>/consumer-api/orgs/<consumer org>/apps' -H 'X-IBM-Consumer-Context: <provider org>.<catalog>' -H 'Authorization: Bearer <bearer_token>'

Get analytics API event data for a catalog:

curl -k -X GET --url 'https://<platform api endpoint>/analytics/<analytics service>/orgs/<provider org>/events' -H 'Authorization: Bearer <bearer_token>'

For provider organization scoped analytics data, use <platform api endpoint>.

For consumer organization scoped analytics data, use <consumer api endpoint>, and /consumer-analytics instead of /analytics. Also include the X-IBM-Consumer-Context header. For example:

curl -k -X GET --url 'https://<consumer api endpoint>/consumer-analytics/orgs/<consumer org>/dashboard' -H 'X-IBM-Consumer-Context: <provider org>.<catalog>' -H 'Authorization: Bearer <bearer_token>'

For more information about querying analytics data with the REST API, see Using the analytics REST API.

Get a list of the availability zones in your API Connect deployment

Use a bearer token that was created with cloud admin user credentials, and specify the platform API endpoint:

curl -k -X GET --url 'https://<platform api endpoint>/api/orgs/admin/availability-zones' -H 'Authorization: Bearer <bearer_token>'

Reference documentation for the API Connect REST APIs: API Connect REST API documentation.

Troubleshooting failed REST API calls

The HTTP return code and error message provide information on the possible causes of the failure:

HTTP 403: Forbidden. Check that your bearer token was created with the correct credentials for the API call.
HTTP 404: Not Found. Verify that your API endpoint URL and path are correct. Are you making a consumer API call on the platform API endpoint?
HTTP 401: Unauthorized. Check that your bearer token is correct and is not expired. If this is returned when you request a bearer token, verify that the username, password, realm, client_id, and client_secret are correct.