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.

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

Add API

Endpoint

/apis/

Request Form Parameters

Attributes Description
name
optional
API name. If none is specified, will default to the public_dns.
public_dns The public DNS address that points to your API. For example, mockbin.com.
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/{id}
Attributes Description
id
required
The unique identifier of the API to be retrieved

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 10
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/{id}
Attributes Description
id
required
The unique identifier of the API to be updated

Request Body

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

Response

HTTP 200 OK
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "name": "Mockbin2",
    "public_dns": "mockbin.com",
    "target_url": "http://mockbin.com",
    "created_at": 1422386534
}

Delete API

Endpoint

/apis/{id}
Attributes Description
id
required
The unique identifier of the API to be deleted

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/{id}
Attributes Description
id
required
The unique identifier of the consumer to be retrieved

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 10
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/{id}
Attributes Description
id
required
The unique identifier of the consumer to be updated

Request Body

{
    "custom_id": "updated_abc123"
}

Response

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

Delete Consumer

Endpoint

/consumers/{id}
Attributes Description
id
required
The unique identifier of the consumer to be deleted

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

/plugins_configurations/

Request Form Parameters

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.
api_id The unique identifier of the API the plugin will be enabled for.
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
}

Retrieve Plugin Configuration

Endpoint

/plugins_configurations/{id}
Attributes Description
id
required
The unique identifier of the plugin configuration to be retrieved

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

List Plugin Configurations

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 10
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

/plugins_configurations/{id}
Attributes Description
id
required
The unique identifier of the plugin configuration to be retrieved

Request Body

{
    "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
}

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
}

Delete Plugin Configuration

Endpoint

/plugins_configurations/{id}
Attributes Description
id
required
The unique identifier of the plugin configuration to be deleted

Response

HTTP 204 NO CONTENT