Careful! You are browsing documentation for an outdated version of Kong. Go here to browse the documentation for the latest version.

Kong 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.

Supported 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:

value.limit=10&value.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:

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

API Object

The API object describes an API that's being exposed by Kong. In order to do that Kong needs to know what is going to be the DNS address that will be pointing to the API, and what is the final target URL of the API where the requests will be proxied. Kong can serve more than one API domain.

{
    "name": "Mockbin",
    "public_dns": "mockbin.com",
    "path": "/someservice",
    "strip_path": false,
    "target_url": "https://mockbin.com"
}

Add API

Endpoint

/apis/

Request Body

Attribute Description
name
optional
The API name. If none is specified, will default to the public_dns.
public_dns
semi-optional
The public DNS address that points to your API. For example, mockbin.com. At least public_dns or path or both should be specified.
path
semi-optional
The public path that points to your API. For example, /someservice. At least public_dns or path or both should be specified.
strip_path
optional
Strip the path value before proxying the request to the final API. For example a request made to /someservice/hello will be resolved to target_url/hello. By default is false.
target_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",
    "public_dns": "mockbin.com",
    "target_url": "http://mockbin.com",
    "created_at": 1422386534
}

Retrieve 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",
    "public_dns": "mockbin.com",
    "target_url": "https://mockbin.com",
    "created_at": 1422386534
}

List APIs

Endpoint

/apis/

Request 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.
public_dns
optional
A filter on the list based on the apis public_dns field.
target_url
optional
A filter on the list based on the apis target_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": 2,
    "data": [
        {
            "id": "4d924084-1adb-40a5-c042-63b19db421d1",
            "name": "Mockbin",
            "public_dns": "mockbin.com",
            "target_url": "https://mockbin.com",
            "created_at": 1422386534
        },
        {
            "id": "3f924084-1adb-40a5-c042-63b19db421a2",
            "name": "PrivateAPI",
            "public_dns": "internal.api.com",
            "target_url": "http://private.api.com",
            "created_at": 1422386585
        }
    ],
    "next": "http://localhost:8001/apis/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}

Update API

Endpoint

/apis/{name or id}
Attributes Description
name or id
required
The unique identifier or the name of the API to update

Request Body

Attribute Description
name
optional
The API name. If none is specified, will default to the public_dns.
public_dns
semi-optional
The public DNS address that points to your API. For example, mockbin.com. At least public_dns or path or both should be specified.
path
semi-optional
The public path that points to your API. For example, /someservice. At least public_dns or path or both should be specified.
strip_path
optional
Strip the path value before proxying the request to the final API. For example a request made to /someservice/hello will be resolved to target_url/hello. By default is false.
target_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",
    "public_dns": "mockbin.com",
    "target_url": "http://mockbin.com",
    "created_at": 1422386534
}

Update Or Create API

Endpoint

/apis/

Request Body

Attribute Description
name
optional
The API name. If none is specified, will default to the public_dns.
public_dns
semi-optional
The public DNS address that points to your API. For example, mockbin.com. At least public_dns or path or both should be specified.
path
semi-optional
The public path that points to your API. For example, /someservice. At least public_dns or path or both should be specified.
strip_path
optional
Strip the path value before proxying the request to the final API. For example a request made to /someservice/hello will be resolved to target_url/hello. By default is false.
target_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.


Delete 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

Consumer 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 be map the consumer list with your database to keep consistency between Kong and your existing primary datastore.

{
    "custom_id": "abc123"
}

Create Consumer

Endpoint

/consumers/

Request 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
}

Retrieve 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
}

List Consumers

Endpoint

/consumers/

Request 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": 2,
    "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=10&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}

Update Consumer

Endpoint

/consumers/{username or id}
Attributes Description
username or id
required
The unique identifier or the username of the consumer to update

Request 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
}

Update Or Create Consumer

Endpoint

/consumers/

Request 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.


Delete 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

Plugin Configuration Object

The Plugin Configuration object 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 Plugin Gallery.

When creating a Plugin Configuration on top of an API, every request made by a client will be evaluated by the plugin configuration you setup. Sometimes the Plugin Configuration 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": "ratelimiting",
    "value": {
        "limit": 20,
        "period": "minute"
    },
    "created_at": 1422386534
}

Create Plugin Configuration

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

Request 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.
value.{property} The configuration properties for the Plugin which can be found on the plugins documentation page in the Plugin Gallery.

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": "ratelimiting",
    "value": {
        "limit": 20,
        "period": "minute"
    },
    "created_at": 1422386534
}

List Per-API Plugin Configurations

Endpoint

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

Request 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": 2,
    "data": [
      {
          "id": "4d924084-1adb-40a5-c042-63b19db421d1",
          "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
          "name": "ratelimiting",
          "value": {
              "limit": 20,
              "period": "minute"
          },
          "created_at": 1422386534
      },
      {
          "id": "3f924084-1adb-40a5-c042-63b19db421a2",
          "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
          "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
          "name": "ratelimiting",
          "value": {
              "limit": 300,
              "period": "hour"
          },
          "created_at": 1422386585
      }
    ],
    "next": "http://localhost:8001/plugins_configurations/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}

List All Plugin Configurations

You can use the /plugins_configuration endpoint to acces a global list of all the configured plugins on your cluster.

Endpoint

/plugins_configurations/

Request 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": 2,
    "data": [
      {
          "id": "4d924084-1adb-40a5-c042-63b19db421d1",
          "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
          "name": "ratelimiting",
          "value": {
              "limit": 20,
              "period": "minute"
          },
          "created_at": 1422386534
      },
      {
          "id": "3f924084-1adb-40a5-c042-63b19db421a2",
          "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
          "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
          "name": "ratelimiting",
          "value": {
              "limit": 300,
              "period": "hour"
          },
          "created_at": 1422386585
      }
    ],
    "next": "http://localhost:8001/plugins_configurations/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}

Update Plugin Configuration

Endpoint

/apis/{api name or id}/plugins/{plugin name or id}
Attributes Description
api name or id
required
The unique identifier or the name of the API for which to update the plugin configuration
plugin configuration name or id
required
The unique identifier or the name of the plugin for which to update the configuration on this API

Request 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.
value.{property} The configuration properties for the Plugin which can be found on the plugins documentation page in the Plugin Gallery.

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": "ratelimiting",
    "value": {
        "limit": 50,
        "period": "second"
    },
    "created_at": 1422386534
}

Update Or Create Plugin Configuration

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

Request 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.
value.{property} The configuration properties for the Plugin which can be found on the plugins documentation page in the Plugin Gallery.

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.


Delete Plugin Configuration

Endpoint

/apis/{api name or id}/plugins/{plugin name or id}
Attributes Description
api name or id
required
The unique identifier or the name of the API for which to delete the plugin configuration
plugin configuration name or id
required
The unique identifier or the name of the plugin for which to delete the configuration on this API

Response

HTTP 204 NO CONTENT