Kong Gateway OSS [ARCHIVE]

0.8.x

PermalinkAdmin API

PermalinkKong Admin API

Kong comes with an internal RESTful API for administration purposes. API commands can be run on any node in the cluster, and Kong will keep the configuration consistent across all nodes.

The RESTful Admin API listens on port 8001 by default.

PermalinkSupported Content Types

The Admin API accepts 2 content types on every endpoint:

x-www-form-urlencoded

Simple enough for basic request bodies, you will probably use it most of the time. Note that when sending nested values, Kong expects nested objects to be referenced with dotted keys. Example:

config.limit=10&config.period=seconds

application/json

Handy for complex bodies (ex: complex plugin configuration), in that case simply send a JSON representaton of the data you want to send. Example:

{
    "config": {
        "limit": 10,
        "period": "seconds"
    }
}

PermalinkInformation routes

PermalinkRetrieve node information

Retrieve generic details about a node.

Endpoint

Response

HTTP 200 OK

{
    "hostname": "",
    "lua_version": "LuaJIT 2.1.0-alpha",
    "plugins": {
        "available_on_server": [
            ...
        ],
        "enabled_in_cluster": [
            ...
        ]
    },
    "configuration" : {
        ...
    },
    "tagline": "Welcome to Kong",
    "version": "0.6.0"
}

* `available_on_server`: Names of plugins that are installed on the node.
* `enabled_in_cluster`: Names of plugins that are enabled/configured. That is, the plugins configurations currently in the datastore shared by all Kong nodes.

PermalinkRetrieve node status

Retrieve usage information about a node, with some basic information about the connections being processed by the underlying nginx process, and the number of entities stored in the datastore collections (including plugin’s collections).

If you want to monitor the Kong process, since Kong is built on top of nginx, every existing nginx monitoring tool or agent can be used.

Endpoint

/status

Response

HTTP 200 OK

{
    "server": {
        "total_requests": 3,
        "connections_active": 1,
        "connections_accepted": 1,
        "connections_handled": 1,
        "connections_reading": 0,
        "connections_writing": 1,
        "connections_waiting": 0
    },
    "database": {
        "apis": 2,
        "consumers": 0,
        "plugins": 2,
        "nodes": 1,
        ...
    }
}

server: Metrics about the nginx HTTP/S server.
- total_requests: The total number of client requests.
- connections_active: The current number of active client connections including Waiting connections.
- connections_accepted: The total number of accepted client connections.
- connections_handled: The total number of handled connections. Generally, the parameter value is the same as accepts unless some resource limits have been reached.
- connections_reading: The current number of connections where Kong is reading the request header.
- connections_writing: The current number of connections where nginx is writing the response back to the client.
- connections_waiting: The current number of idle client connections waiting for a request.
database: Metrics about the database collections.
- ...: For every database collection, shows the number of items stored in that collection.

PermalinkCluster

You can see the Kong cluster members, and forcibly remove a node from the cluster, using the following endpoints. For more information read the clustering documentation. You can also execute these operations using the CLI.

PermalinkRetrieve cluster status

Retrieve the cluster status, returning information for each node in the cluster.

Endpoint

/cluster

Response

HTTP 200 OK

{
    "total": 3,
    "data": [
        {
            "address": "192.168.1.107:7946",
            "name": "kong.prod1_7946",
            "status": "alive"
        },
        {
            "address": "192.168.2.127:7946",
            "name": "kong.prod2_7946",
            "status": "failed"
        },
        {
            "address": "192.168.3.112:8484",
            "name": "kong.prod3_8484",
            "status": "left"
        }
    ]
}

PermalinkForcibly remove a node

Forcibly remove a node from the cluster.

Endpoint

/cluster

Response

HTTP 200 OK

PermalinkAPI Object

The API object describes an API that’s being exposed by Kong. Kong needs to know how to retrieve the API when a consumer is calling it from the Proxy port. Each API object must specify a request host, a request path or both. Kong will proxy all requests to the API to the specified upstream URL.

{
    "name": "Mockbin",
    "request_host": "mockbin.com",
    "request_path": "/someservice",
    "strip_request_path": false,
    "preserve_host": false,
    "upstream_url": "https://mockbin.com"
}

PermalinkAdd API

Endpoint

/apis/

PermalinkRequest Body

Attribute	Description
`name` optional	The API name. If none is specified, will default to the `request_host` or `request_path`.
`request_host` semi-optional	The public DNS address that points to your API. For example, `mockbin.com`. At least `request_host` or `request_path` or both should be specified.
`request_path` semi-optional	The public path that points to your API. For example, `/someservice`. At least `request_host` or `request_path` or both should be specified.
`strip_request_path` optional	Strip the `request_path` value before proxying the request to the final API. For example a request made to `/someservice/hello` will be resolved to `upstream_url/hello`. By default is `false`.
`preserve_host` optional	Preserves the original `Host` header sent by the client, instead of replacing it with the hostname of the `upstream_url`. By default is `false`.
`upstream_url`	The base target URL that points to your API server, this URL will be used for proxying requests. For example, `https://mockbin.com`.

Response

HTTP 201 Created

{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "name": "Mockbin",
    "request_host": "mockbin.com",
    "upstream_url": "http://mockbin.com",
    "preserve_host": false,
    "created_at": 1422386534
}

PermalinkRetrieve API

Endpoint

/apis/{name or id}

Attributes	Description
`name or id` required	The unique identifier or the name of the API to retrieve

Response

HTTP 200 OK

{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "name": "Mockbin",
    "request_host": "mockbin.com",
    "upstream_url": "https://mockbin.com",
    "preserve_host": false,
    "created_at": 1422386534
}

PermalinkList APIs

Endpoint

/apis/

PermalinkRequest Querystring Parameters

Attributes	Description
`id` optional	A filter on the list based on the apis `id` field.
`name` optional	A filter on the list based on the apis `name` field.
`request_host` optional	A filter on the list based on the apis `request_host` field.
`request_path` optional	A filter on the list based on the apis `request_path` field.
`upstream_url` optional	A filter on the list based on the apis `upstream_url` field.
`size` optional, default is 100	A limit on the number of objects to be returned.
`offset` optional	A cursor used for pagination. `offset` is an object identifier that defines a place in the list.

Response

HTTP 200 OK

{
    "total": 10,
    "data": [
        {
            "id": "4d924084-1adb-40a5-c042-63b19db421d1",
            "name": "Mockbin",
            "request_host": "mockbin.com",
            "upstream_url": "https://mockbin.com",
            "preserve_host": false,
            "created_at": 1422386534
        },
        {
            "id": "3f924084-1adb-40a5-c042-63b19db421a2",
            "name": "PrivateAPI",
            "request_host": "internal.api.com",
            "upstream_url": "http://private.api.com",
            "preserve_host": false,
            "created_at": 1422386585
        }
    ],
    "next": "http://localhost:8001/apis/?size=2&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}

PermalinkUpdate API

Endpoint

/apis/{name or id}

Attributes	Description
`name or id` required	The unique identifier or the name of the API to update

PermalinkRequest Body

Attribute	Description
`name` optional	The API name. If none is specified, will default to the `request_host` or `request_path`.
`request_host` semi-optional	The public DNS address that points to your API. For example, `mockbin.com`. At least `request_host` or `request_path` or both should be specified.
`request_path` semi-optional	The public path that points to your API. For example, `/someservice`. At least `request_host` or `request_path` or both should be specified.
`strip_request_path` optional	Strip the `request_path` value before proxying the request to the final API. For example a request made to `/someservice/hello` will be resolved to `upstream_url/hello`. By default is `false`.
`preserve_host` optional	Preserves the original `Host` header sent by the client, instead of replacing it with the hostname of the `upstream_url`. By default is `false`.
`upstream_url`	The base target URL that points to your API server, this URL will be used for proxying requests. For example, `https://mockbin.com`.

Response

HTTP 200 OK

{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "name": "Mockbin2",
    "request_host": "mockbin.com",
    "upstream_url": "http://mockbin.com",
    "preserve_host": false,
    "created_at": 1422386534
}

PermalinkUpdate Or Create API

Endpoint

/apis/

PermalinkRequest Body

Attribute	Description
`name` optional	The API name. If none is specified, will default to the `request_host` or `request_path`.
`request_host` semi-optional	The public DNS address that points to your API. For example, `mockbin.com`. At least `request_host` or `request_path` or both should be specified.
`request_path` semi-optional	The public path that points to your API. For example, `/someservice`. At least `request_host` or `request_path` or both should be specified.
`strip_request_path` optional	Strip the `request_path` value before proxying the request to the final API. For example a request made to `/someservice/hello` will be resolved to `upstream_url/hello`. By default is `false`.
`preserve_host` optional	Preserves the original `Host` header sent by the client, instead of replacing it with the hostname of the `upstream_url`. By default is `false`.
`upstream_url`	The base target URL that points to your API server, this URL will be used for proxying requests. For example, `https://mockbin.com`.

The body needs an id parameter to trigger an update on an existing entity.

Response

HTTP 201 Created or HTTP 200 OK

See POST and PATCH responses.

PermalinkDelete API

Endpoint

/apis/{name or id}

Attributes	Description
`name or id` required	The unique identifier or the name of the API to delete

Response

HTTP 204 No Content

PermalinkConsumer Object

The Consumer object represents a consumer - or a user - of an API. You can either rely on Kong as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong and your existing primary datastore.

{
    "custom_id": "abc123"
}

PermalinkCreate Consumer

Endpoint

/consumers/

PermalinkRequest Form Parameters

Attributes	Description
`username` semi-optional	The username of the consumer. You must send either this field or `custom_id` with the request.
`custom_id` semi-optional	Field for storing an existing ID for the consumer, useful for mapping Kong with users in your existing database. You must send either this field or `username` with the request.

Response

HTTP 201 Created

{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "custom_id": "abc123",
    "created_at": 1422386534
}

PermalinkRetrieve Consumer

Endpoint

/consumers/{username or id}

Attributes	Description
`username or id` required	The unique identifier or the username of the consumer to retrieve

Response

HTTP 200 OK

{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "custom_id": "abc123",
    "created_at": 1422386534
}

PermalinkList Consumers

Endpoint

/consumers/

PermalinkRequest Querystring Parameters

Attributes	Description
`id` optional	A filter on the list based on the consumer `id` field.
`custom_id` optional	A filter on the list based on the consumer `custom_id` field.
`username` optional	A filter on the list based on the consumer `username` field.
`size` optional, default is 100	A limit on the number of objects to be returned.
`offset` optional	A cursor used for pagination. `offset` is an object identifier that defines a place in the list.

Response

HTTP 200 OK

{
    "total": 10,
    "data": [
        {
            "id": "4d924084-1adb-40a5-c042-63b19db421d1",
            "custom_id": "abc123",
            "created_at": 1422386534
        },
        {
            "id": "3f924084-1adb-40a5-c042-63b19db421a2",
            "custom_id": "def345",
            "created_at": 1422386585
        }
    ],
    "next": "http://localhost:8001/consumers/?size=2&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}

PermalinkUpdate Consumer

Endpoint

/consumers/{username or id}

Attributes	Description
`username or id` required	The unique identifier or the username of the consumer to update

PermalinkRequest Body

Attributes	Description
`username` semi-optional	The username of the consumer. You must send either this field or `custom_id` with the request.
`custom_id` semi-optional	Field for storing an existing ID for the consumer, useful for mapping Kong with users in your existing database. You must send either this field or `username` with the request.

Response

HTTP 200 OK

{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "custom_id": "updated_abc123",
    "created_at": 1422386534
}

PermalinkUpdate Or Create Consumer

Endpoint

/consumers/

PermalinkRequest Body

Attributes	Description
`username` semi-optional	The username of the consumer. You must send either this field or `custom_id` with the request.
`custom_id` semi-optional	Field for storing an existing ID for the consumer, useful for mapping Kong with users in your existing database. You must send either this field or `username` with the request.

The body needs an id parameter to trigger an update on an existing entity.

Response

HTTP 201 Created or HTTP 200 OK

See POST and PATCH responses.

PermalinkDelete Consumer

Endpoint

/consumers/{username or id}

Attributes	Description
`username or id` required	The unique identifier or the name of the consumer to delete

Response

HTTP 204 No Content

PermalinkPlugin Object

A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response workflow, and it’s how you can add functionalities to APIs that run behind Kong, like Authentication or Rate Limiting for example. You can find more information about how to install and what values each plugin takes by visiting the Kong Hub.

When creating adding Plugin on top of an API, every request made by a client will be evaluated by the Plugin’s configuration you setup. Sometimes the Plugin needs to be tuned to different values for some specific consumers, you can do that by specifying the consumer_id value.

{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
    "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
    "name": "rate-limiting",
    "config": {
        "minute": 20,
        "hour": 500
    },
    "enabled": true,
    "created_at": 1422386534
}

PermalinkAdd Plugin

Endpoint

/apis/{name or id}/plugins/

Attributes	Description
`name or id` required	The unique identifier or the name of the API on which to add a plugin configuration

PermalinkRequest Body

Attributes	Description
`name`	The name of the Plugin that’s going to be added. Currently the Plugin must be installed in every Kong instance separately.
`consumer_id` optional	The unique identifier of the consumer that overrides the existing settings for this specific consumer on incoming requests.
`config.{property}`	The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub.
`enabled`	Whether the plugin is applied. Default: `true`.

Response

HTTP 201 Created

{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
    "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
    "name": "rate-limiting",
    "config": {
        "minute": 20,
        "hour": 500
    },
    "enabled": true,
    "created_at": 1422386534
}

PermalinkRetrieve Plugin

/plugins/{id}

PermalinkRequest Querystring Parameters

Attributes	Description
`id` required	The unique identifier of the plugin to retrieve

Response

HTTP 200 OK

{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
    "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
    "name": "rate-limiting",
    "config": {
        "minute": 20,
        "hour": 500
    },
    "enabled": true,
    "created_at": 1422386534
}

PermalinkList All Plugins

Endpoint

/plugins/

PermalinkRequest Querystring Parameters

Attributes	Description
`id` optional	A filter on the list based on the `id` field.
`name` optional	A filter on the list based on the `name` field.
`api_id` optional	A filter on the list based on the `api_id` field.
`consumer_id` optional	A filter on the list based on the `consumer_id` field.
`size` optional, default is 100	A limit on the number of objects to be returned.
`offset` optional	A cursor used for pagination. `offset` is an object identifier that defines a place in the list.

Response

HTTP 200 OK

{
    "total": 10,
    "data": [
      {
          "id": "4d924084-1adb-40a5-c042-63b19db421d1",
          "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
          "name": "rate-limiting",
          "config": {
              "minute": 20,
              "hour": 500
          },
          "enabled": true,
          "created_at": 1422386534
      },
      {
          "id": "3f924084-1adb-40a5-c042-63b19db421a2",
          "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
          "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
          "name": "rate-limiting",
          "config": {
              "minute": 300,
              "hour": 20000
          },
          "enabled": true,
          "created_at": 1422386585
      }
    ],
    "next": "http://localhost:8001/plugins?size=2&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}

PermalinkList Plugins per API

Endpoint

/apis/{api name or id}/plugins/

PermalinkRequest Querystring Parameters

Attributes	Description
`id` optional	A filter on the list based on the `id` field.
`name` optional	A filter on the list based on the `name` field.
`api_id` optional	A filter on the list based on the `api_id` field.
`consumer_id` optional	A filter on the list based on the `consumer_id` field.
`size` optional, default is 100	A limit on the number of objects to be returned.
`offset` optional	A cursor used for pagination. `offset` is an object identifier that defines a place in the list.

Response

HTTP 200 OK

{
    "total": 10,
    "data": [
      {
          "id": "4d924084-1adb-40a5-c042-63b19db421d1",
          "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
          "name": "rate-limiting",
          "config": {
              "minute": 20,
              "hour": 500
          },
          "enabled": true,
          "created_at": 1422386534
      },
      {
          "id": "3f924084-1adb-40a5-c042-63b19db421a2",
          "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
          "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
          "name": "rate-limiting",
          "config": {
              "minute": 300,
              "hour": 20000
          },
          "enabled": true,
          "created_at": 1422386585
      }
    ],
    "next": "http://localhost:8001/plugins?size=2&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}

PermalinkUpdate Plugin

Endpoint

/apis/{api name or id}/plugins/{id}

Attributes	Description
`api name or id` required	The unique identifier or the name of the API for which to update the plugin configuration
`id` required	The unique identifier of the plugin configuration to update on this API

PermalinkRequest Body

Attributes	Description
`name`	The name of the Plugin that’s going to be added. Currently the Plugin must be installed in every Kong instance separately.
`consumer_id` optional	The unique identifier of the consumer that overrides the existing settings for this specific consumer on incoming requests.
`config.{property}`	The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub.
`enabled`	Whether the plugin is applied. Default: `true`.

Response

HTTP 200 OK

{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
    "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
    "name": "rate-limiting",
    "config": {
        "minute": 20,
        "hour": 500
    },
    "enabled": true,
    "created_at": 1422386534
}

PermalinkUpdate or Add Plugin

Endpoint

/apis/{api name or id}/plugins/

Attributes	Description
`api name or id` required	The unique identifier or the name of the API for which to update or create the plugin configuration

PermalinkRequest Body

Attributes	Description
`name`	The name of the Plugin that’s going to be added. Currently the Plugin must be installed in every Kong instance separately.
`consumer_id` optional	The unique identifier of the consumer that overrides the existing settings for this specific consumer on incoming requests.
`config.{property}`	The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub.
`enabled`	Whether the plugin is applied. Default: `true`.

The body needs an id parameter to trigger an update on an existing entity.

Response

HTTP 201 Created or HTTP 200 OK

See POST and PATCH responses.

PermalinkDelete Plugin

Endpoint

/apis/{api name or id}/plugins/{id}

Attributes	Description
`api name or id` required	The unique identifier or the name of the API for which to delete the plugin configuration
`id` required	The unique identifier of the plugin configuration to delete on this API

Response

HTTP 204 No Content

PermalinkRetrieve Enabled Plugins

Retrieve a list of all installed plugins on the Kong node.

Endpoint

/plugins/enabled

Response

HTTP 200 OK

{
    "enabled_plugins": [
        "ssl",
        "jwt",
        "acl",
        "cors",
        "oauth2",
        "tcp-log",
        "udp-log",
        "file-log",
        "http-log",
        "key-auth",
        "hmac-auth",
        "basic-auth",
        "ip-restriction",
        "mashape-analytics",
        "request-transformer",
        "response-transformer",
        "request-size-limiting",
        "rate-limiting",
        "response-ratelimiting"
    ]
}

PermalinkRetrieve Plugin Schema

Retrieve the schema of a plugin’s configuration. This is useful to understand what fields a plugin accepts, and can be used for building third-party integrations to the Kong’s plugin system.

/plugins/schema/{plugin name}

Response

HTTP 200 OK

{
    "fields": {
        "hide_credentials": {
            "default": false,
            "type": "boolean"
        },
        "key_names": {
            "default": "function",
            "required": true,
            "type": "array"
        }
    }
}