All guides
  1. Home
  2. Technical guides
  3. APIs

APIsIntermediate level

Basic structure of an API in IBM API Connect 10

7 min read

All guides

Basic structure of an API in IBM API Connect 10

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-configuration extension.
  • 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 apic CLI.

Prerequisites

  • Access to IBM API Connect 10 (API Manager) with a provider organisation and a catalog (for example, sandbox).
  • The API Connect toolkit (apic CLI) 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

PieceWhat 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.
CatalogThe environment where the product is published: sandbox for testing, and the ones you create (for example, production).
Consumer applicationThe developer registers it in the portal, gets its Client ID and Client Secret and subscribes it to a plan.
GatewayThe 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 servers entry with no variables in its URL, no callbacks or links (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_id or client_secret; with the names X-IBM-Client-Id and X-IBM-Client-Secret it 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 validate policy and transform responses with map.
  • Automate validation and publishing with apic from a pipeline (see the CI/CD with GitHub Actions guide).
  • Define a production catalog with subscription approval and strict limits.

Share

More guides on

See all guides

Other technical guides

See all guides

IntegrationIntermediate

TIBCO ActiveSpaces 5.2: basic administration commands

The day-to-day commands in TIBCO ActiveSpaces 5.2: realm service on FTL servers, tibdg, grid definition, tables, starting processes, status, scaling with copysets, checkpoints and logs.

Read the guide 8 min read

DevOpsBasic

Basic CI/CD structure with GitHub Actions

A complete pipeline with GitHub Actions: tests on every push and pull request, a Docker image in GitHub Container Registry and deployment to a protected environment, with a workflow ready to copy.

Read the guide 6 min read

DevelopmentBasic

Java Spring Boot development best practices

The practices that make the biggest difference in a Spring Boot service: structure, constructor injection, DTOs, validation, errors, configuration, transactions, logs, comments, tests and automated quality.

Read the guide 7 min read

Contact

Build your next competitive advantage today

Let’s talk about how we can help you. We will reply with a clear technical proposal, with no obligation.

Request information

Fields marked with are required.