# Basic structure of an API in IBM API Connect 10

A Bitflow Solutions guide. Web version: https://bitflow-solutions.com/en/guias-tecnicas/ibm-api-connect-10-api-structure/

## 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

### OpenAPI 2.0 or 3.0

- 2.0: both gateways
- 3.0: DataPower API Gateway only; a single servers entry with no variables; no callbacks, links or OpenID Connect; API keys not in cookies

### x-ibm-configuration

```yaml
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
```

### Complete API (orders_1.0.0.yaml)

```yaml
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
```

Note: target-url with $(target-url)$(api.operation.path) is the pattern recommended in the IBM community; check it in your version.

### Product (orders-product_1.0.0.yaml)

```yaml
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
```

### Log in

```powershell
# 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
```

### Create with the toolkit

```powershell
apic create:api --title "Orders" --version 1.0.0 --gateway-type datapower-api-gateway --target-url https://backend.company.local/orders
apic create:product
```

### Validate

```powershell
apic validate orders_1.0.0.yaml
apic validate orders-product_1.0.0.yaml
```

### Publish

```powershell
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
```

### Test

```powershell
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.

Source: IBM API Connect v10 documentation (ibm.com/docs) and CLI reference (ibm-apiconnect.github.io/clidocs).
