The following defines the v2 interface for managing APIs using the OpenAPI 2.0 spec.
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.
Create a new managed API.
tenant_id
: *(string) the tenant associated with this APIExample 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 APImanaged_url
: the base url to use to invoke this APIopen_api_doc
: the OpenAPI docOnce you have created your API, you can invoke this API by concatenating the managed_url
with a path specified in your OpenAPI doc.
Update an existing managed API.
tenant_id
: *(string) the tenant associated with this APIreturns:
{ "artifact_id": (string), "managed_url": (string), "open_api_doc": (object) }
artifact_id
: the id associated with this APImanaged_url
: the base url to use to invoke this APIopen_api_doc
: the OpenAPI docGet all managed APIs for a tenant.
tenant_id
: *(string) the tenant associated with this APIreturns:
[ { "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 APImanaged_url
: the base url to use to invoke this APIopen_api_doc
: the OpenAPI docGet a specific managed API for a tenant by its id.
tenant_id
: *(string) the tenant associated with this APIartifact_id
: *(string) the id associated with this APIreturns:
{ "artifact_id": (string), "managed_url": (string), "open_api_doc": (object) }
artifact_id
: the id associated with this APImanaged_url
: the base url to use to invoke this APIopen_api_doc
: the OpenAPI docDelete a specific managed API for a tenant by its id.
tenant_id
: *(string) the tenant associated with this APIartifact_id
: *(string) the id associated with this APIreturns:
204 No Content
Create a client_id and/or client_secret for a managed API.
tenant_id
: *(string) the tenant associated with this APIbody:
{ artifact_id: *(string), client_id: *(string), client_secret: (string) }
artifact_id
: the id associated with this APIclient_id
: the client id associated with this subscription for this APIclient_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 all subscriptions associated with a managed API.
tenant_id
: *(string) the tenant associated with this APIartifact_id
: *(string) the id associated with this APIreturns:
[ client_id_1, client_id_2, ... ]
Delete a specific subscription for an API.
tenant_id
: *(string) the tenant associated with this APIclient_id
: *(string) the client id associated with this subscription for this APIartifact_id
: *(string) the id associated with this APIreturns:
204 No Content
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 urltarget-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": [] } } ] } }
operations
array for each case, specify the operationId
of the path to which you want the target-url
to applyClient 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" } }
apiKey
is supported for the “type” field and only header
is supported for the “in” fieldRate 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 unitsrate
: the number of allowed calls for the specified timeCORS
Enable or disable CORS (Cross-Origin Resource Sharing) using the x-gateway-configuration
extension.
Example:
"x-gateway-configuration": { "cors": { "enabled": true }, ... }
true
and false