Introduction

Within IBM Cloud, you can easily create API proxies and custom APIs backed by IBM Cloud Functions, Cloud Foundry apps, and App Connect flows. An API Gateway service enables you to securely share your APIs with other developers.

The API Gateway service can handle APIs located in IBM Cloud resource groups. APIs located in Cloud Foundry spaces are handled by an automatically-provisioned Legacy API Gateway. Both gateway types are tightly integrated with IBM Cloud common services like Log Analysis, Activity Tracker, App ID, Certificate Manager, and more.

API endpoint

https://api.<region>.apigw.cloud.ibm.com

Replace <region> with the prefix that represents the geographic area where your APIs reside. For more informaton, see Managing API Gateway with the REST API.

Authentication

Most API methods require an Authorization header that includes a token with your IBM Cloud Identity and Access Management (IAM) credentials.

The header should look like this: Authorization: Bearer <token>

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully.

HTTP Error Code Description Recovery
200 Success The request was successful.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact your account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized.
404 Not Found The requested resource could not be found.
408 Request Timeout The connection to the server timed out. Wait a few minutes, then try again.
409 Conflict The entity is already in the requested state.
429 Too Many Requests You have made too many requests to this endpoint and are being rate limited / throttled.
500 Internal Server Error App ID is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Methods

Get details for all Endpoints

GET /v2/endpoints
Request

Custom Headers

  • Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens

Query Parameters

  • The API Gateway service instance CRN

  • Provider Id

  • Only return shared endpoints

  • Only return managed endpoints

  • Return OpenAPI doc with list results. Possible values are ['provider', 'consumer']. Defaults to 'provider'

  • curl -X GET \
      -H 'Authorization: Bearer <IAM token>' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/endpoints?service_instance_crn={crn}'
Response

Status Code

  • Request was successful

Example responses
  • [
      {
        "artifact_id": "851c6ffe-7da6-41ab-a8fa-501bd0557001",
        "crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891:endpoint:851c6ffe-7da6-41ab-a8fa-501bd0557001",
        "parent_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891::",
        "service_instance_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891::",
        "account_id": "e139a1ed8c1a770c128cc80cb07f426f",
        "metadata": {},
        "provider_id": "user-defined",
        "name": "test",
        "routes": [],
        "managed_url": "https://gw.us-south.apigw.test.appdomain.cloud/api/abd7714cf04e470d102926d22f7a13fc3c3ff49c00e992f0e20119e61e914a67/",
        "alias_url": "https://497c007a.us-south.stage1.apiconnect.appdomain.cloud/",
        "shared": false,
        "managed": true,
        "base_path": "/"
      }
    ]

Create an Endpoint

POST /v2/endpoints
Request

Custom Headers

  • User IAM token

Information about the new endpoint

  • curl -X POST \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer <IAM token>' \
      -d '{ "artifact_id": "33521683-fd54-4cde-8e37-cdeaa7b0a80f", "service_instance_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:86164525-fd54-4cde-8e37-cdeaa7b0a80f::", "parent_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:86164525-fd54-4cde-8e37-cdeaa7b0a80f::", "name": "example", "routes": [ "https://httpbin.org" ], "managed": false, "metadata": {}, "open_api_doc": {} }' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/endpoints'
Response

Status Code

  • Request was successful

Example responses
  • {
      "artifact_id": "851c6ffe-7da6-41ab-a8fa-501bd0557001",
      "crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891:endpoint:851c6ffe-7da6-41ab-a8fa-501bd0557001",
      "parent_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891::",
      "service_instance_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891::",
      "account_id": "e139a1ed8c1a770c128cc80cb07f426f",
      "metadata": {},
      "provider_id": "user-defined",
      "name": "test",
      "routes": [],
      "managed_url": "https://gw.us-south.apigw.test.appdomain.cloud/api/abd7714cf04e470d102926d22f7a13fc3c3ff49c00e992f0e20119e61e914a67/",
      "alias_url": "https://497c007a.us-south.stage1.apiconnect.appdomain.cloud/",
      "shared": false,
      "managed": true,
      "base_path": "/"
    }

Get details for a given Endpoint

GET /v2/endpoints/{id}
Request

Custom Headers

  • User IAM token

Path Parameters

  • Endpoint Id

Query Parameters

  • Service Instance CRN

  • curl -X GET \
      -H 'Authorization: Bearer <IAM token>' \
      -H 'Accept: application/json' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/endpoints/{id}?service_instance_crn={crn}'
Response

Status Code

  • Request was successful

Example responses
  • {
      "artifact_id": "851c6ffe-7da6-41ab-a8fa-501bd0557001",
      "crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891:endpoint:851c6ffe-7da6-41ab-a8fa-501bd0557001",
      "parent_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891::",
      "service_instance_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891::",
      "account_id": "e139a1ed8c1a770c128cc80cb07f426f",
      "metadata": {},
      "provider_id": "user-defined",
      "name": "test",
      "routes": [],
      "managed_url": "https://gw.us-south.apigw.test.appdomain.cloud/api/abd7714cf04e470d102926d22f7a13fc3c3ff49c00e992f0e20119e61e914a67/",
      "alias_url": "https://497c007a.us-south.stage1.apiconnect.appdomain.cloud/",
      "shared": false,
      "managed": true,
      "base_path": "/"
    }

Update an endpoint

PUT /v2/endpoints/{id}
Request

Custom Headers

  • User IAM token

Path Parameters

  • Endpoint Id

Query Parameters

  • Service Instance CRN

Information about the endpoint

  • curl -X PUT \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer <IAM token>' \
      -d '{ "artifact_id": "33521683-fd54-4cde-8e37-cdeaa7b0a80f", "service_instance_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:86164525-fd54-4cde-8e37-cdeaa7b0a80f::", "parent_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:86164525-fd54-4cde-8e37-cdeaa7b0a80f::", "name": "example", "routes": [ "https://httpbin.org" ], "managed": false, "metadata": {}, "open_api_doc": {} }' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/endpoints'
Response

Status Code

  • Request was successful

Example responses
  • {
      "artifact_id": "851c6ffe-7da6-41ab-a8fa-501bd0557001",
      "crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891:endpoint:851c6ffe-7da6-41ab-a8fa-501bd0557001",
      "parent_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891::",
      "service_instance_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891::",
      "account_id": "e139a1ed8c1a770c128cc80cb07f426f",
      "metadata": {},
      "provider_id": "user-defined",
      "name": "test",
      "routes": [],
      "managed_url": "https://gw.us-south.apigw.test.appdomain.cloud/api/abd7714cf04e470d102926d22f7a13fc3c3ff49c00e992f0e20119e61e914a67/",
      "alias_url": "https://497c007a.us-south.stage1.apiconnect.appdomain.cloud/",
      "shared": false,
      "managed": true,
      "base_path": "/"
    }

Delete an Endpoint

DELETE /v2/endpoints/{id}
Request

Custom Headers

  • User IAM token

Path Parameters

  • Endpoint id

Query Parameters

  • Service Instance CRN

  • curl -X DELETE \
      -H 'Authorization: Bearer <IAM token>' \
      -H 'Accept: application/json' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/endpoints/{id}?service_instance_crn={crn}'
Response

Status Code

  • No Content - The request was successful

No Sample Response

This method does not specify any sample responses.

Get the OpenAPI doc for a given Endpoint

GET /v2/endpoints/{id}/swagger
Request

Custom Headers

  • User IAM token

Path Parameters

  • Endpoint Id

Query Parameters

  • Service Instance CRN

  • Type of swagger to retrieve

    Allowable values: [json,yaml]

    Default: json

  • curl -X GET \
      -H 'Authorization: Bearer <IAM token>' \
      -H 'Accept: application/json' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/endpoints/{id}/swagger?service_instance_crn={crn}'
Response

Status Code

  • Request was successful

Example responses
  • {
      "info": {
        "version": "1.0",
        "title": "example"
      },
      "x-ibm-configuration": {
        "assembly": {
          "execute": [
            {
              "invoke": {
                "target-url": "https://httpbin.org",
                "verb": "keep"
              }
            }
          ]
        }
      },
      "basePath": "/c636f62e-7d47-48bf-8e1d-b90c58762816",
      "paths": {
        "/": {
          "get": {
            "description": "Default get resource for endpoint",
            "responses": {
              "200": {
                "description": "A successful invocation response"
              }
            }
          }
        }
      }
    }

Execute actions for a given Endpoint

POST /v2/endpoints/{id}/actions
Request

Custom Headers

  • User IAM token

Path Parameters

  • Endpoint Id

Query Parameters

  • Service Instance CRN

  • Provider Id

Information about the requested action

  • curl -X POST \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer <IAM token>' \
      -d '{ "type": "manage" }' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/endpoints/{id}/actions?service_instance_crn={crn}?provider_id=user-defined'
Response

Status Code

  • Request was successful

Example responses
  • {
      "artifact_id": "851c6ffe-7da6-41ab-a8fa-501bd0557001",
      "crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891:endpoint:851c6ffe-7da6-41ab-a8fa-501bd0557001",
      "parent_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891::",
      "service_instance_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891::",
      "account_id": "e139a1ed8c1a770c128cc80cb07f426f",
      "metadata": {},
      "provider_id": "user-defined",
      "name": "test",
      "routes": [],
      "managed_url": "https://gw.us-south.apigw.test.appdomain.cloud/api/abd7714cf04e470d102926d22f7a13fc3c3ff49c00e992f0e20119e61e914a67/",
      "alias_url": "https://497c007a.us-south.stage1.apiconnect.appdomain.cloud/",
      "shared": false,
      "managed": true,
      "base_path": "/"
    }

Get provider sorted summary about all Endpoints

GET /v2/endpoints/summary
Request

Custom Headers

  • User IAM token

Query Parameters

  • User account ID

  • Service Instance CRN

  • Return OpenAPI doc with list results. Possible values are ['provider', 'consumer']. Defaults to 'provider'

  • curl -X GET \
      -H 'Authorization: Bearer <IAM token>' \
      -H 'Accept: application/json' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/endpoints/summary?account_id={account_id}'
Response

Status Code

  • Request was successful

Example responses
  • [
      {
        "service_instance_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891::",
        "endpoints": [
          {
            "artifact_id": "851c6ffe-7da6-41ab-a8fa-501bd0557001",
            "crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891:endpoint:851c6ffe-7da6-41ab-a8fa-501bd0557001",
            "parent_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891::",
            "service_instance_crn": "crn:v1:staging:public:api-gateway:global:a/e139a1ed8c1a770c128cc80cb07f426f:612b125f-480e-44a2-96a9-daeee4bf1891::",
            "account_id": "e139a1ed8c1a770c128cc80cb07f426f",
            "metadata": {},
            "provider_id": "user-defined",
            "name": "test",
            "routes": [],
            "managed_url": "https://gw.us-south.apigw.test.appdomain.cloud/api/abd7714cf04e470d102926d22f7a13fc3c3ff49c00e992f0e20119e61e914a67/",
            "alias_url": "https://497c007a.us-south.stage1.apiconnect.appdomain.cloud/",
            "shared": false,
            "managed": true,
            "base_path": "/"
          }
        ]
      }
    ]

Get all subscriptions tied to a given artifact

GET /v2/subscriptions
Request

Custom Headers

  • User bearer token

Query Parameters

  • Artifact Id

  • Subscription type

  • curl -X GET \
      -H 'Authorization: Bearer <IAM token>' \
      -H 'Accept: application/json' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/subscriptions?artifact_id={artifact_id}
Response

List of all subscriptions tied to a given artifact

Status Code

  • Request was successful

Example responses
  • [
      {
        "client_id": "62bc8a5f-480e-1e52-9229-daee77da1890",
        "secret_provided": true,
        "artifact_id": "392ffa5f-433e-1e52-2139-fe131f183c90",
        "account_id": "e139a1ed8c1a770c128cc80cb07f426f",
        "name": "example",
        "type": null,
        "metadata": {}
      }
    ]

Create a subscription for an artifact

POST /v2/subscriptions
Request

Custom Headers

  • User bearer token

Subscription

  • curl -X POST \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer <IAM token>' \
      -d '{ "client_id": "47712f48-fa6c-11e9-aad5-362b9e155667", "client_secret": "be9f8a5c-fa6b-11e9-8f0b-362b9e155667", "artifact_id": "62bc8a5f-480e-1e52-9229-daee77da1890" }' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/subscriptions'
Response

Status Code

  • Request was successful

Example responses
  • {
      "client_id": "62bc8a5f-480e-1e52-9229-daee77da1890",
      "secret_provided": true,
      "artifact_id": "392ffa5f-433e-1e52-2139-fe131f183c90",
      "account_id": "e139a1ed8c1a770c128cc80cb07f426f",
      "name": "example",
      "type": null,
      "metadata": {}
    }

Get subscription for a given clientid

GET /v2/subscriptions/{id}
Request

Custom Headers

  • User bearer token

Path Parameters

  • Client Id

Query Parameters

  • Artifact Id

  • curl -X GET \
      -H 'Authorization: Bearer <IAM token>' \
      -H 'Accept: application/json' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/subscriptions/{subscription_id}?artifact_id={artifact_id}
Response

Status Code

  • Request was successful

Example responses
  • {
      "client_id": "62bc8a5f-480e-1e52-9229-daee77da1890",
      "secret_provided": true,
      "artifact_id": "392ffa5f-433e-1e52-2139-fe131f183c90",
      "account_id": "e139a1ed8c1a770c128cc80cb07f426f",
      "name": "example",
      "type": null,
      "metadata": {}
    }

Update a subscription

PUT /v2/subscriptions/{id}
Request

Custom Headers

  • User bearer token

Path Parameters

  • Client Id

Query Parameters

  • Artifact Id

Subscription

  • curl -X PUT \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer <IAM token>' \
      -d '{ "client_id": "47712f48-fa6c-11e9-aad5-362b9e155667", "client_secret": "be9f8a5c-fa6b-11e9-8f0b-362b9e155667",  "artifact_id": "62bc8a5f-480e-1e52-9229-daee77da1890" }' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/subscriptions/{subscription_id}?artifact_id={artifact_id}'
Response

Status Code

  • Request was successful

Example responses
  • {
      "client_id": "62bc8a5f-480e-1e52-9229-daee77da1890",
      "secret_provided": true,
      "artifact_id": "392ffa5f-433e-1e52-2139-fe131f183c90",
      "account_id": "e139a1ed8c1a770c128cc80cb07f426f",
      "name": "example",
      "type": null,
      "metadata": {}
    }

Delete a subscription

DELETE /v2/subscriptions/{id}
Request

Custom Headers

  • User bearer token

Path Parameters

  • Client Id

Query Parameters

  • Artifact Id

  • curl -X DELETE \
      -H 'Authorization: Bearer <IAM token>' \
      -H 'Accept: application/json' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/subscriptions/{subscription_id}?artifact_id={artifact_id}
Response

Status Code

  • Request was successful

No Sample Response

This method does not specify any sample responses.

Get artifact associated to a subscription

GET /v2/subscriptions/artifact
Request

Query Parameters

  • Artifact Id

  • Client Id

  • curl -X GET \
      -H 'Authorization: Bearer <IAM token>' \
      -H 'Accept: application/json' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/subscriptions/artifact?artifact_id={id}
Response

Subscription artifact requested

Status Code

  • Request was successful

Example responses
  • {
      "open_api_doc": {
        "info": {
          "version": "1.0",
          "title": "example"
        },
        "x-ibm-configuration": {
          "assembly": {
            "execute": [
              {
                "invoke": {
                  "target-url": "https://httpbin.org",
                  "verb": "keep"
                }
              }
            ]
          }
        },
        "basePath": "/c636f62e-7d47-48bf-8e1d-b90c58762816",
        "paths": {
          "/": {
            "get": {
              "description": "Default get resource for endpoint",
              "responses": {
                "200": {
                  "description": "A successful invocation response"
                }
              }
            }
          }
        }
      },
      "managed_url": "https://gw.us-south.apigw.test.appdomain.cloud/api/abd7714cf04e470d102926d22f7a13fc3c3ff49c00e992f0e20119e61e914a67/"
    }

Add a Subscription Secret

PUT /v2/subscriptions/{id}/secret
Request

Custom Headers

  • Client id

Path Parameters

  • Client Id

Query Parameters

  • Artifact Id

Subscription Secret Request

  • curl -X PUT \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer <IAM token>' \
      -d '{ "client_secret": "be9f8a5c-fa6b-11e9-8f0b-362b9e155667" }' \
      'https://api.us-south.apigw.cloud.ibm.com/controller/v2/subscriptions/{subscription_id}/secret?artifact_id={artifact_id}'
Response

Status Code

  • Request was successful

Example responses
  • {
      "client_id": "62bc8a5f-480e-1e52-9229-daee77da1890",
      "secret_provided": true,
      "artifact_id": "392ffa5f-433e-1e52-2139-fe131f183c90",
      "account_id": "e139a1ed8c1a770c128cc80cb07f426f",
      "name": "example",
      "type": null,
      "metadata": {}
    }