{"id":5180,"date":"2026-11-18T21:22:56","date_gmt":"2026-11-18T21:22:56","guid":{"rendered":"https:\/\/bitflow-solutions.com\/guias-tecnicas\/ibm-api-connect-10-api-structure\/"},"modified":"2026-11-18T21:22:56","modified_gmt":"2026-11-18T21:22:56","slug":"ibm-api-connect-10-api-structure","status":"publish","type":"bf_guia","link":"https:\/\/bitflow-solutions.com\/en\/guias-tecnicas\/ibm-api-connect-10-api-structure\/","title":{"rendered":"Basic structure of an API in IBM API Connect 10"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">The <strong>basic structure of an API<\/strong> in <strong>IBM API Connect 10<\/strong> with the DataPower API Gateway: the OpenAPI contract with the <code>x-ibm-configuration<\/code> extension, protection with a Client ID and Client Secret, the product with its plans, and validation and publishing with the <code>apic<\/code> CLI. Based on IBM\u2019s official documentation, with the complete API and product in the <strong>README.md<\/strong> on the left.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">What you\u2019ll learn<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>The pieces of API Connect 10: API, product, plans, catalogs and applications.<\/li>\n\n\n<li>The structure of an API: the OpenAPI contract and the <code>x-ibm-configuration<\/code> extension.<\/li>\n\n\n<li>How to protect the API with a Client ID and Client Secret.<\/li>\n\n\n<li>How to define a product with plans and call limits.<\/li>\n\n\n<li>Validate, publish and test the API with the <code>apic<\/code> CLI.<\/li>\n\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Prerequisites<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Access to <strong>IBM API Connect 10<\/strong> (API Manager) with a provider organisation and a catalog (for example, <code>sandbox<\/code>).<\/li>\n\n\n<li>The <strong>API Connect toolkit<\/strong> (<code>apic<\/code> CLI) of the same version as your server, on Windows with PowerShell.<\/li>\n\n\n<li>A backend service to forward the calls to.<\/li>\n\n\n<li>Know the basics of OpenAPI (see the OpenAPI 3 contract with OAuth and API Key guide).<\/li>\n\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Step by step<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">1. Understand the pieces<\/h3>\n\n\n\n<figure class=\"wp-block-table\"><table><thead><tr><th>Piece<\/th><th>What it is<\/th><\/tr><\/thead><tbody><tr><td><strong>API<\/strong> (YAML)<\/td><td>The OpenAPI contract plus the <code>x-ibm-configuration<\/code> extension, which tells the gateway how to process each call.<\/td><\/tr><tr><td><strong>Product<\/strong> (YAML)<\/td><td>Packages one or more APIs and defines the <strong>plans<\/strong> (call limits) under which they are offered.<\/td><\/tr><tr><td><strong>Catalog<\/strong><\/td><td>The environment where the product is published: <code>sandbox<\/code> for testing, and the ones you create (for example, production).<\/td><\/tr><tr><td><strong>Consumer application<\/strong><\/td><td>The developer registers it in the portal, gets its <strong>Client ID<\/strong> and <strong>Client Secret<\/strong> and subscribes it to a plan.<\/td><\/tr><tr><td><strong>Gateway<\/strong><\/td><td>The DataPower API Gateway (recommended) or the v5-compatible one, which runs the API.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\">2. Choose the OpenAPI version<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>OpenAPI 2.0<\/strong> (Swagger) works on both types of gateway. It is the one we use in this guide.<\/li>\n\n\n<li><strong>OpenAPI 3.0<\/strong> only works on the <strong>DataPower API Gateway<\/strong> and with limitations: a single <code>servers<\/code> entry with no variables in its URL, no <code>callbacks<\/code> or <code>links<\/code> (an API that has them is not published), no OpenID Connect and no API keys in cookies.<\/li>\n\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">3. Get to know the x-ibm-configuration extension<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">It is what turns an OpenAPI contract into an API that can run on the gateway:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>x-ibm-configuration:\n  gateway: datapower-api-gateway   # or datapower-gateway (v5-compatible gateway)\n  type: rest                       # rest or wsdl\n  phase: realized                  # identified, specified or realized\n  enforced: true                   # the gateway enforces the API\n  testable: true                   # can be tested from API Manager\n  cors:\n    enabled: true\n  properties: {}                   # default values (for example, target-url)\n  catalogs: {}                     # per-catalog values (sandbox, production\u2026)\n  assembly:\n    execute: []                    # the policies, in order<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">The policies in <code>assembly.execute<\/code> run in order. The most common ones: <code>invoke<\/code> (call the backend), <code>set-variable<\/code>, <code>map<\/code>, <code>validate<\/code>, <code>gatewayscript<\/code>, <code>switch<\/code> or <code>operation-switch<\/code>, <code>ratelimit<\/code> and <code>log<\/code>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">4. Write the API<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">An orders API that forwards the calls to the backend and requires a Client ID and Client Secret. The backend URL is a property (<code>target-url<\/code>) with a different value for the <code>sandbox<\/code> catalog:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>swagger: '2.0'\ninfo:\n  title: Orders\n  version: 1.0.0\nbasePath: \/orders\/v1\nschemes:\n  - https\nconsumes:\n  - application\/json\nproduces:\n  - application\/json\n\nsecurityDefinitions:\n  clientId:\n    type: apiKey\n    in: header\n    name: X-IBM-Client-Id\n  clientSecret:\n    type: apiKey\n    in: header\n    name: X-IBM-Client-Secret\nsecurity:\n  - clientId: []\n    clientSecret: []\n\nx-ibm-configuration:\n  gateway: datapower-api-gateway\n  type: rest\n  phase: realized\n  enforced: true\n  testable: true\n  cors:\n    enabled: true\n  properties:\n    target-url:\n      value: https:\/\/backend.company.local\/orders\n      description: URL of the backend service\n  catalogs:\n    sandbox:\n      properties:\n        target-url: https:\/\/backend-pre.company.local\/orders\n  assembly:\n    execute:\n      - invoke:\n          version: 2.0.0\n          title: Call the backend\n          target-url: $(target-url)$(api.operation.path)\n\npaths:\n  \/orders:\n    get:\n      operationId: listOrders\n      summary: Lists the orders\n      responses:\n        '200':\n          description: List of orders\n  \/orders\/{orderId}:\n    get:\n      operationId: getOrder\n      summary: Retrieves an order\n      parameters:\n        - name: orderId\n          in: path\n          required: true\n          type: string\n      responses:\n        '200':\n          description: The order\n        '404':\n          description: The order does not exist<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">About the <code>invoke<\/code> URL: IBM states that you should not manually add the operation\u2019s path or parameters to <code>target-url<\/code>. The <code>$(target-url)$(api.operation.path)<\/code> pattern for forwarding each operation\u2019s path is the one recommended in the IBM community (<code>$(request.path)<\/code> also includes the <code>basePath<\/code>); check it in your version with the API Manager test tool.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">5. Protect the API with a Client ID and Client Secret<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The two <code>apiKey<\/code> 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\u2019s.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>At most two API key definitions: one for the Client ID and one for the Client Secret.<\/li>\n\n\n<li>The Client Secret requires the Client ID, and both must be in the same place (header or query).<\/li>\n\n\n<li>On the DataPower API Gateway, the header name is free if you specify the type with <code>x-key-type: client_id<\/code> or <code>client_secret<\/code>; with the names <code>X-IBM-Client-Id<\/code> and <code>X-IBM-Client-Secret<\/code> it works on both gateways.<\/li>\n\n\n<li>For OAuth, the API is linked to an API Connect OAuth provider and combined with the Client ID definition.<\/li>\n\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">6. Define the product and its plans<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">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, <code>-<\/code> or <code>_<\/code>) of up to 20 characters:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>product: 1.0.0\ninfo:\n  name: orders-product\n  title: Orders product\n  version: 1.0.0\ngateways:\n  - datapower-api-gateway\nvisibility:\n  view:\n    enabled: true\n    type: public\n    tags: []\n    orgs: []\n  subscribe:\n    enabled: true\n    type: authenticated\n    tags: []\n    orgs: []\nplans:\n  basic:\n    title: Basic\n    description: 100 calls per hour\n    approval: false\n    rate-limits:\n      default:\n        value: 100\/hour\n        hard-limit: false\n  premium:\n    title: Premium\n    description: 1000 calls per hour, with approval\n    approval: true\n    rate-limits:\n      default:\n        value: 1000\/hour\n        hard-limit: true\napis:\n  orders:\n    $ref: orders_1.0.0.yaml<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Limits are written as <code>100\/hour<\/code> or <code>50\/1hour<\/code> (or <code>unlimited<\/code>). With <code>hard-limit: true<\/code>, calls that exceed the limit are rejected.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">7. Log in with the CLI<\/h3>\n\n\n\n<pre class=\"wp-block-code\"><code># List the user registries (realms) of the management server\napic identity-providers:list --scope provider --server api-manager.company.local --fields title,realm\n\n# Log in to the provider organisation\napic login --server api-manager.company.local --username developer --realm provider\/default-idp-2<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">If your installation uses single sign-on, the toolkit offers <code>apic login --server &lt;server&gt; --sso<\/code>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">8. Create the files with the toolkit (optional)<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Instead of writing them from scratch, the toolkit generates the API and the product, which you then complete:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>apic create:api --title \"Orders\" --version 1.0.0 --gateway-type datapower-api-gateway --target-url https:\/\/backend.company.local\/orders\napic create:product<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">9. Validate the API and the product<\/h3>\n\n\n\n<pre class=\"wp-block-code\"><code>apic validate orders_1.0.0.yaml\napic validate orders-product_1.0.0.yaml<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><code>--no-extensions<\/code> validates only the standard OpenAPI part, and <code>--product-only<\/code> the product without its APIs.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">10. Publish to the catalog<\/h3>\n\n\n\n<pre class=\"wp-block-code\"><code>apic products:publish orders-product_1.0.0.yaml --server api-manager.company.local --org company --catalog sandbox\napic logout --server api-manager.company.local<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">To avoid repeating the catalog in every command: <code>apic config:set catalog=...<\/code>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">11. Test the API as a consumer<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Register an application in the catalog\u2019s 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 <code>basePath<\/code>:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Invoke-RestMethod -Uri \"https:\/\/gateway.company.local\/company\/sandbox\/orders\/v1\/orders\" -Headers @{\n  \"X-IBM-Client-Id\"     = $env:CLIENT_ID\n  \"X-IBM-Client-Secret\" = $env:CLIENT_SECRET\n}<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Common errors<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">The API with OpenAPI 3.0 is not published<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">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 <code>servers<\/code> entry, variables in its URL, <code>callbacks<\/code> or <code>links<\/code>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">401 when calling the API<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The Client ID or Client Secret headers are missing, they don\u2019t belong to an application subscribed to a plan of this product in this catalog, or the subscription is pending approval.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">404 when calling the API<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The URL doesn\u2019t match: check the organisation, the catalog and the <code>basePath<\/code>, that the product is published in that catalog and that the path and its parameters match those in <code>paths<\/code>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">The backend receives an incorrect path<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Don\u2019t manually add the path or the query to <code>target-url<\/code>. Check which variable you use to forward the path (<code>api.operation.path<\/code> does not include the <code>basePath<\/code>; <code>request.path<\/code> does).<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">\u201capic validate\u201d reports errors in x-ibm-configuration<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\"><code>phase<\/code>, <code>enforced<\/code>, <code>testable<\/code> and <code>cors.enabled<\/code> are required, and all keys are case-sensitive.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">The product is published but the API doesn\u2019t appear in the plan<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">An API has to be in the product\u2019s <code>apis<\/code> section for a plan to include it, with the correct reference to its file.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">The CLI won\u2019t let you log in<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Use a toolkit of the same version as the server and the correct realm (<code>provider\/...<\/code> for a provider organisation); <code>apic identity-providers:list<\/code> tells you which ones exist.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Next steps<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>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).<\/li>\n\n\n<li>Validate requests against the contract with the <code>validate<\/code> policy and transform responses with <code>map<\/code>.<\/li>\n\n\n<li>Automate validation and publishing with <code>apic<\/code> from a pipeline (see the CI\/CD with GitHub Actions guide).<\/li>\n\n\n<li>Define a production catalog with subscription approval and strict limits.<\/li>\n\n<\/ul>\n\n\n","protected":false},"excerpt":{"rendered":"<p>How an API is structured in IBM API Connect 10: OpenAPI contract with x-ibm-configuration, Client ID and Client Secret, product with plans and limits, and validation and publishing with the apic CLI.<\/p>\n","protected":false},"featured_media":0,"template":"","bf_tecnologia":[101],"bf_nivel":[109],"class_list":["post-5180","bf_guia","type-bf_guia","status-publish","hentry","bf_tecnologia-apis-en","bf_nivel-intermediate"],"acf":[],"_links":{"self":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_guia\/5180","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_guia"}],"about":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/types\/bf_guia"}],"version-history":[{"count":0,"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_guia\/5180\/revisions"}],"wp:attachment":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/media?parent=5180"}],"wp:term":[{"taxonomy":"bf_tecnologia","embeddable":true,"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_tecnologia?post=5180"},{"taxonomy":"bf_nivel","embeddable":true,"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_nivel?post=5180"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}