Management Interface v2

The following defines the v2 interface for managing APIs using the OpenAPI 2.0 spec.

API

See below for details on how to create, update, and delete managed APIs inside the apigateway, as well as how to manage subscription keys for securing the managed APIs. Note that these endpoints are exposed on port 9000.

POST /v2/{tenant_id}/apis

Create a new managed API.

tenant_id: *(string) the tenant associated with this API
The body is a JSON object that follows the OpenAPI 2.0 spec, with additional gateway-specific extensions

Example body:

{
  "swagger": "2.0",
  "info": {
    "version": "1.0",
    "title": "Hello World API"
  },
  "basePath": "/hw",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/hello": {
      "get": {
        "description": "Returns a greeting to the user!",
        "operationId": "getHello",
        "responses": {
          "200": {
            "description": "Returns the greeting.",
            "schema": {
              "type": "string"
            }
          }
        }
      }
    },
    "/foo": {
      "get": {
        "description": "Returns bar to the user.",
        "operationId": "getFoo",
        "responses": {
          "200": {
            "description": "Returns bar.",
            "schema": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "securityDefinitions": {
    "client_id": {
      "type": "apiKey",
      "name": "X-Api-Key",
      "in": "header"
    }
  },
  "security": [
    {
      "client_id": []
    }
  ],
  "x-gateway-rate-limit": [
    {
      "unit": "minute",
      "units": 3,
      "rate": 100
    }
  ],
  "x-gateway-configuration": {
    "assembly": {
      "execute": [
        {
          "operation-switch": {
            "case": [
              {
                "operations": [
                  "getHello"
                ],
                "execute": [
                  {
                    "invoke": {
                      "target-url": "https://openwhisk.ng.bluemix.net/api/some/action/path.http",
                      "verb": "keep"
                    }
                  }
                ]
              },
              {
                "operations": [
                  "getFoo"
                ],
                "execute": [
                  {
                    "invoke": {
                      "target-url": "https://openwhisk.ng.bluemix.net/api/another/action/path.http",
                      "verb": "keep"
                    }
                  }
                ]
              }
            ],
            "otherwise": []
          }
        }
      ]
    }
  }
}

returns:

{
  "artifact_id": (string),
  "managed_url": (string),
  "open_api_doc": (object)
}

artifact_id: the id associated with this API
managed_url: the base url to use to invoke this API
open_api_doc: the OpenAPI doc

Once you have created your API, you can invoke this API by concatenating the managed_url with a path specified in your OpenAPI doc.

PUT /v2/{tenant_id}/apis/{artifact_id}

Update an existing managed API.

tenant_id: *(string) the tenant associated with this API
artifact_id: *(string) the id associated with this API
The body is a JSON object that represents this API's OpenAPI 2.0 spec, as described above

returns:

{
  "artifact_id": (string),
  "managed_url": (string),
  "open_api_doc": (object)
}

artifact_id: the id associated with this API
managed_url: the base url to use to invoke this API
open_api_doc: the OpenAPI doc

GET /v2/{tenant_id}/apis

Get all managed APIs for a tenant.

tenant_id: *(string) the tenant associated with this API

returns:

[
  {
    "artifact_id": (string),
    "managed_url": (string),
    "open_api_doc": (object)
  },
  {
    "artifact_id": (string),
    "managed_url": (string),
    "open_api_doc": (object)
  },
  ...
]

artifact_id: the id associated with this API
managed_url: the base url to use to invoke this API
open_api_doc: the OpenAPI doc

GET /v2/{tenant_id}/apis/{artifact_id}

Get a specific managed API for a tenant by its id.

tenant_id: *(string) the tenant associated with this API
artifact_id: *(string) the id associated with this API

returns:

{
  "artifact_id": (string),
  "managed_url": (string),
  "open_api_doc": (object)
}

artifact_id: the id associated with this API
managed_url: the base url to use to invoke this API
open_api_doc: the OpenAPI doc

DELETE /v2/{tenant_id}/apis/{artifact_id}

Delete a specific managed API for a tenant by its id.

tenant_id: *(string) the tenant associated with this API
artifact_id: *(string) the id associated with this API

returns:

204 No Content

POST /v2/{tenant_id}/subscriptions

Create a client_id and/or client_secret for a managed API.

tenant_id: *(string) the tenant associated with this API

body:

{
  artifact_id: *(string),
  client_id: *(string),
  client_secret: (string)
}

artifact_id: the id associated with this API
client_id: the client id associated with this subscription for this API
client_secret: optional client secret associated with this subscription for this API. Note that once a client_secret has been created, there is no way to retrieve its value as it is stored as a hash inside the gateway.

returns:

{
  "message": "Subscription 'clientId' created for API 'artifactId'"
}

GET /v2/{tenant_id}/subscriptions?artifact_id={artifact_id}

Get all subscriptions associated with a managed API.

tenant_id: *(string) the tenant associated with this API
artifact_id: *(string) the id associated with this API

returns:

[
  client_id_1,
  client_id_2,
  ...
]

DELETE /v2/{tenant_id}/subscriptions/{client_id}?artifact_id={artifact_id}

Delete a specific subscription for an API.

tenant_id: *(string) the tenant associated with this API
client_id: *(string) the client id associated with this subscription for this API
artifact_id: *(string) the id associated with this API

returns:

204 No Content

Gateway-specific Extensions

See below for a list of policies that are supported in the gateway and how they can be configured inside the OpenAPI doc.

Target-url and Operation-switch

Set the target-url (ie. the backend for your API) for all paths using the invoke policy inside the x-gateway-configuration extension.

Example:

"x-gateway-configuration": {
  "assembly": {
    "execute": [
      {
        "invoke": {
          "target-url": "https://openwhisk.ng.bluemix.net/api/some/action/path.http",
          "verb": "keep"
        }
      },
      ...
    ]
  }
}

target-url: the backend url
- optional: to pass the path of your managed url down to the target-url, append /${request.path} to the end of target-url. Eg. "target-url": "https://openwhisk.ng.bluemix.net/api/some/action/path.http/${request.path}"
verb: the method to use when invoking the target-url (use “keep” to use the keep the same verb as the API)

To set a different target-url for different paths, use the operation-switch policy inside x-gateway-configuration.

Example:

"x-gateway-configuration": {
  "assembly": {
    "execute": [
      {
        "operation-switch": {
          "case": [
            {
              "operations": [
                "getHello"
              ],
              "execute": [
                {
                  "invoke": {
                    "target-url": "https://openwhisk.ng.bluemix.net/api/some/action/path.http",
                    "verb": "keep"
                  }
                }
              ]
            },
            {
              "operations": [
                "postHello"
              ],
              "execute": [
                {
                  "invoke": {
                    "target-url": "https://openwhisk.ng.bluemix.net/api/another/action/path.http",
                    "verb": "keep"
                  }
                }
              ]
            }
          ],
          "otherwise": []
        }
      }
    ]
  }
}

inside the operations array for each case, specify the operationId of the path to which you want the target-url to apply

Client Id and Client Secret
Secure your managed API with a client id and an optional client secret.
Example:
```
"securityDefinitions": {
  "client_id": {
    "type": "apiKey",
    "name": "X-Api-Key",
    "in": "header"
  },
  "client_secret": {
    "type": "apiKey",
    "name": "X-Api-Secret",
    "in": "header"
  }
}
```
- Currently, only apiKey is supported for the “type” field and only header is supported for the “in” field
- Client ids and client secrets can be created using the Subscriptions API described in the API section
Rate Limiting
Rate limit your managed API using the Leaky Bucket algorithm.
Example:
```
"x-gateway-rate-limit": [
  {
    "unit": "minute",
    "units": 3,
    "rate": 100
  }
]
```
- unit: a string representing the unit of time (eg. “second”, “minute”, “hour”, “day”)
- units: the number of units
- rate: the number of allowed calls for the specified time
CORS
Enable or disable CORS (Cross-Origin Resource Sharing) using the x-gateway-configuration extension.
Example:
```
"x-gateway-configuration": {
  "cors": {
    "enabled": true
  },
  ...
}
```
- valid values for the “enabled” field are true and false