The basic structure of an API in IBM API Connect 10 with the DataPower API Gateway: the OpenAPI contract with the x-ibm-configuration extension, protection with a Client ID and Client Secret, the product with its plans, and validation and publishing with the apic CLI. Based on IBM’s official documentation, with the complete API and product in the README.md on the left.
What you’ll learn
- The pieces of API Connect 10: API, product, plans, catalogs and applications.
- The structure of an API: the OpenAPI contract and the
x-ibm-configurationextension. - How to protect the API with a Client ID and Client Secret.
- How to define a product with plans and call limits.
- Validate, publish and test the API with the
apicCLI.
Prerequisites
- Access to IBM API Connect 10 (API Manager) with a provider organisation and a catalog (for example,
sandbox). - The API Connect toolkit (
apicCLI) of the same version as your server, on Windows with PowerShell. - A backend service to forward the calls to.
- Know the basics of OpenAPI (see the OpenAPI 3 contract with OAuth and API Key guide).
Step by step
1. Understand the pieces
| Piece | What it is |
|---|---|
| API (YAML) | The OpenAPI contract plus the x-ibm-configuration extension, which tells the gateway how to process each call. |
| Product (YAML) | Packages one or more APIs and defines the plans (call limits) under which they are offered. |
| Catalog | The environment where the product is published: sandbox for testing, and the ones you create (for example, production). |
| Consumer application | The developer registers it in the portal, gets its Client ID and Client Secret and subscribes it to a plan. |
| Gateway | The DataPower API Gateway (recommended) or the v5-compatible one, which runs the API. |
2. Choose the OpenAPI version
- OpenAPI 2.0 (Swagger) works on both types of gateway. It is the one we use in this guide.
- OpenAPI 3.0 only works on the DataPower API Gateway and with limitations: a single
serversentry with no variables in its URL, nocallbacksorlinks(an API that has them is not published), no OpenID Connect and no API keys in cookies.
3. Get to know the x-ibm-configuration extension
It is what turns an OpenAPI contract into an API that can run on the gateway:
x-ibm-configuration:
gateway: datapower-api-gateway # or datapower-gateway (v5-compatible gateway)
type: rest # rest or wsdl
phase: realized # identified, specified or realized
enforced: true # the gateway enforces the API
testable: true # can be tested from API Manager
cors:
enabled: true
properties: {} # default values (for example, target-url)
catalogs: {} # per-catalog values (sandbox, production…)
assembly:
execute: [] # the policies, in order
The policies in assembly.execute run in order. The most common ones: invoke (call the backend), set-variable, map, validate, gatewayscript, switch or operation-switch, ratelimit and log.
4. Write the API
An orders API that forwards the calls to the backend and requires a Client ID and Client Secret. The backend URL is a property (target-url) with a different value for the sandbox catalog:
swagger: '2.0'
info:
title: Orders
version: 1.0.0
basePath: /orders/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
securityDefinitions:
clientId:
type: apiKey
in: header
name: X-IBM-Client-Id
clientSecret:
type: apiKey
in: header
name: X-IBM-Client-Secret
security:
- clientId: []
clientSecret: []
x-ibm-configuration:
gateway: datapower-api-gateway
type: rest
phase: realized
enforced: true
testable: true
cors:
enabled: true
properties:
target-url:
value: https://backend.company.local/orders
description: URL of the backend service
catalogs:
sandbox:
properties:
target-url: https://backend-pre.company.local/orders
assembly:
execute:
- invoke:
version: 2.0.0
title: Call the backend
target-url: $(target-url)$(api.operation.path)
paths:
/orders:
get:
operationId: listOrders
summary: Lists the orders
responses:
'200':
description: List of orders
/orders/{orderId}:
get:
operationId: getOrder
summary: Retrieves an order
parameters:
- name: orderId
in: path
required: true
type: string
responses:
'200':
description: The order
'404':
description: The order does not exist
About the invoke URL: IBM states that you should not manually add the operation’s path or parameters to target-url. The $(target-url)$(api.operation.path) pattern for forwarding each operation’s path is the one recommended in the IBM community ($(request.path) also includes the basePath); check it in your version with the API Manager test tool.
5. Protect the API with a Client ID and Client Secret
The two apiKey definitions in the example identify the consumer application: the gateway checks that the Client ID belongs to an application subscribed to a plan of the product, and that the Client Secret is that application’s.
- At most two API key definitions: one for the Client ID and one for the Client Secret.
- The Client Secret requires the Client ID, and both must be in the same place (header or query).
- On the DataPower API Gateway, the header name is free if you specify the type with
x-key-type: client_idorclient_secret; with the namesX-IBM-Client-IdandX-IBM-Client-Secretit works on both gateways. - For OAuth, the API is linked to an API Connect OAuth provider and combined with the Client ID definition.
6. Define the product and its plans
The product offers the API in two plans: a basic one, with no approval, and another with more calls that requires approval. Plan names are a single word (letters, numbers, - or _) of up to 20 characters:
product: 1.0.0
info:
name: orders-product
title: Orders product
version: 1.0.0
gateways:
- datapower-api-gateway
visibility:
view:
enabled: true
type: public
tags: []
orgs: []
subscribe:
enabled: true
type: authenticated
tags: []
orgs: []
plans:
basic:
title: Basic
description: 100 calls per hour
approval: false
rate-limits:
default:
value: 100/hour
hard-limit: false
premium:
title: Premium
description: 1000 calls per hour, with approval
approval: true
rate-limits:
default:
value: 1000/hour
hard-limit: true
apis:
orders:
$ref: orders_1.0.0.yaml
Limits are written as 100/hour or 50/1hour (or unlimited). With hard-limit: true, calls that exceed the limit are rejected.
7. Log in with the CLI
# List the user registries (realms) of the management server
apic identity-providers:list --scope provider --server api-manager.company.local --fields title,realm
# Log in to the provider organisation
apic login --server api-manager.company.local --username developer --realm provider/default-idp-2
If your installation uses single sign-on, the toolkit offers apic login --server <server> --sso.
8. Create the files with the toolkit (optional)
Instead of writing them from scratch, the toolkit generates the API and the product, which you then complete:
apic create:api --title "Orders" --version 1.0.0 --gateway-type datapower-api-gateway --target-url https://backend.company.local/orders
apic create:product
9. Validate the API and the product
apic validate orders_1.0.0.yaml
apic validate orders-product_1.0.0.yaml
--no-extensions validates only the standard OpenAPI part, and --product-only the product without its APIs.
10. Publish to the catalog
apic products:publish orders-product_1.0.0.yaml --server api-manager.company.local --org company --catalog sandbox
apic logout --server api-manager.company.local
To avoid repeating the catalog in every command: apic config:set catalog=....
11. Test the API as a consumer
Register an application in the catalog’s portal, subscribe it to a plan and use its Client ID and Client Secret. The gateway URL includes the organisation and the catalog in front of the basePath:
Invoke-RestMethod -Uri "https://gateway.company.local/company/sandbox/orders/v1/orders" -Headers @{
"X-IBM-Client-Id" = $env:CLIENT_ID
"X-IBM-Client-Secret" = $env:CLIENT_SECRET
}
Common errors
The API with OpenAPI 3.0 is not published
Either the product uses the v5-compatible gateway (OpenAPI 3.0 only works on the DataPower API Gateway), or the contract has something unsupported: more than one servers entry, variables in its URL, callbacks or links.
401 when calling the API
The Client ID or Client Secret headers are missing, they don’t belong to an application subscribed to a plan of this product in this catalog, or the subscription is pending approval.
404 when calling the API
The URL doesn’t match: check the organisation, the catalog and the basePath, that the product is published in that catalog and that the path and its parameters match those in paths.
The backend receives an incorrect path
Don’t manually add the path or the query to target-url. Check which variable you use to forward the path (api.operation.path does not include the basePath; request.path does).
“apic validate” reports errors in x-ibm-configuration
phase, enforced, testable and cors.enabled are required, and all keys are case-sensitive.
The product is published but the API doesn’t appear in the plan
An API has to be in the product’s apis section for a plan to include it, with the correct reference to its file.
The CLI won’t let you log in
Use a toolkit of the same version as the server and the correct realm (provider/... for a provider organisation); apic identity-providers:list tells you which ones exist.
Next steps
- Add an OAuth provider and require a token as well as the Client ID (see the OpenAPI 3 contract with OAuth and API Key guide).
- Validate requests against the contract with the
validatepolicy and transform responses withmap. - Automate validation and publishing with
apicfrom a pipeline (see the CI/CD with GitHub Actions guide). - Define a production catalog with subscription approval and strict limits.