Maybe you were looking for the Enterprise Edition (EE) Documentation instead?
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 Admin API for administration purposes. Requests to the Admin API can be sent to any node in the cluster, and Kong will keep the configuration consistent across all nodes.

  • 8001 is the default port on which the Admin API listens.
  • 8444 is the default port for HTTPS traffic to the Admin API.

This API is designed for internal use and provides full control over Kong, so care should be taken when setting up Kong environments to avoid undue public exposure of this API. See this document for a discussion of methods to secure the Admin API.

Supported Content Types

The Admin API accepts 2 content types on every endpoint:

  • application/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 representation of the data you want to send. Example:

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

Information routes

Retrieve node information

Retrieve generic details about a node.

Endpoint

/

Response

HTTP 200 OK
{
    "hostname": "",
    "node_id": "6a72192c-a3a1-4c8d-95c6-efabae9fb969",
    "lua_version": "LuaJIT 2.1.0-beta3",
    "plugins": {
        "available_on_server": [
            ...
        ],
        "enabled_in_cluster": [
            ...
        ]
    },
    "configuration" : {
        ...
    },
    "tagline": "Welcome to Kong",
    "version": "0.13.0"
}
  • node_id: A UUID representing the running Kong node. This UUID is randomly generated when Kong starts, so the node will have a different node_id each time it is restarted.
  • 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.

Retrieve node status

Retrieve usage information about a node, with some basic information about the connections being processed by the underlying nginx process, and the status of the database connection.

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": {
        "reachable": true
    }
}
  • 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.
    • reachable: A boolean value reflecting the state of the database connection. Please note that this flag does not reflect the health of the database itself.

Service Object

Service entities, as the name implies, are abstractions of each of your own upstream services. Examples of Services would be a data transformation microservice, a billing API, etc.

The main attribute of a Service is its URL (where Kong should proxy traffic to), which can be set as a single string or by specifying its protocol, host, port and path individually.

Services are associated to Routes (a Service can have many Routes associated with it). Routes are entry-points in Kong and define rules to match client requests. Once a Route is matched, Kong proxies the request to its associated Service. See the Proxy Reference for a detailed explanation of how Kong proxies traffic.

{
    "id": "4e13f54a-bbf1-47a8-8777-255fed7116f2",
    "created_at": 1488869076800,
    "updated_at": 1488869076800,
    "connect_timeout": 60000,
    "protocol": "http",
    "host": "example.org",
    "port": 80,
    "path": "/api",
    "name": "example-service",
    "retries": 5,
    "read_timeout": 60000,
    "write_timeout": 60000
}


Add Service

Endpoint

/services/

Request Body

Attributes Description
name
optional
The Service name.
protocol The protocol used to communicate with the upstream. It can be one of http (default) or https.
host The host of the upstream server.
port The upstream server port. Defaults to 80.
path
optional
The path to be used in requests to the upstream server. Empty by default.
retries
optional
The number of retries to execute upon failure to proxy. The default is 5.
connect_timeout
optional
The timeout in milliseconds for establishing a connection to the upstream server. Defaults to 60000.
write_timeout
optional
The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Defaults to 60000.
read_timeout
optional
The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Defaults to 60000.
url
shorthand-attribute
Shorthand attribute to set protocol, host, port and path at once. This attribute is write-only (the Admin API never "returns" the url).

Response

HTTP 201 Created
{
    "id": "4e13f54a-bbf1-47a8-8777-255fed7116f2",
    "created_at": 1488869076800,
    "updated_at": 1488869076800,
    "connect_timeout": 60000,
    "protocol": "http",
    "host": "example.org",
    "port": 80,
    "path": "/api",
    "name": "example-service",
    "retries": 5,
    "read_timeout": 60000,
    "write_timeout": 60000
}


Retrieve Service

Endpoints

/services/{name or id}
Attributes Description
name or id
required
The unique identifier or the name of the Service to retrieve.
/routes/{route id}/service
Attributes Description
route id
required
The unique identifier of a Route belonging to the Service to be retrieved.

Response

HTTP 200 OK
{
    "id": "4e13f54a-bbf1-47a8-8777-255fed7116f2",
    "created_at": 1488869076800,
    "updated_at": 1488869076800,
    "connect_timeout": 60000,
    "protocol": "http",
    "host": "example.org",
    "port": 80,
    "path": "/api",
    "name": "example-service",
    "retries": 5,
    "read_timeout": 60000,
    "write_timeout": 60000
}


List Services

Endpoint

/services/

Request Querystring Parameters

Attributes Description
offset
optional
A cursor used for pagination. offset is an object identifier that defines a place in the list.
size
optional, default is 100 max is 1000
A limit on the number of objects to be returned per page.

Response

HTTP 200 OK
{
    "data": [{
        "id": "4e13f54a-bbf1-47a8-8777-255fed7116f2",
        "created_at": 1488869076800,
        "updated_at": 1488869076800,
        "connect_timeout": 60000,
        "protocol": "http",
        "host": "example.org",
        "port": 80,
        "path": "/api",
        "name": "example-service",
        "retries": 5,
        "read_timeout": 60000,
        "write_timeout": 60000
    }, {
        "id": "8e13faaa-ee42-44ea-8421-255bc12316a1",
        "created_at": 1488869077320,
        "updated_at": 1488869077320,
        "connect_timeout": 60000,
        "protocol": "http",
        "host": "example2.org",
        "port": 80,
        "path": "/api",
        "name": "example-service2",
        "retries": 5,
        "read_timeout": 60000,
        "write_timeout": 60000
    }],
    "next": "http://localhost:8001/services?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

Update Service

Endpoints

/services/{name or id}
Attributes Description
name or id
required
The id or the name attribute of the Service to update.
/routes/{route id}/service
Attributes Description
route id
required
The id attribute of the Route whose Service is to be updated.

Request Body

Attributes Description
name
optional
The Service name.
protocol The protocol used to communicate with the upstream. It can be one of http (default) or https.
host The host of the upstream server.
port The upstream server port. Defaults to 80.
path
optional
The path to be used in requests to the upstream server. Empty by default.
retries
optional
The number of retries to execute upon failure to proxy. The default is 5.
connect_timeout
optional
The timeout in milliseconds for establishing a connection to the upstream server. Defaults to 60000.
write_timeout
optional
The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Defaults to 60000.
read_timeout
optional
The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Defaults to 60000.
url
shorthand-attribute
Shorthand attribute to set protocol, host, port and path at once. This attribute is write-only (the Admin API never "returns" the url).

Response

HTTP 200 OK
{
    "id": "4e13f54a-bbf1-47a8-8777-255fed7116f2",
    "created_at": 1488869076800,
    "updated_at": 1488869076800,
    "connect_timeout": 60000,
    "protocol": "http",
    "host": "example.org",
    "port": 80,
    "path": "/api",
    "name": "example-service",
    "retries": 5,
    "read_timeout": 60000,
    "write_timeout": 60000
}


Delete Service

Endpoint

/services/{name or id}
Attributes Description
name or id
required
The id or the name attribute of the Service to delete.

Response

HTTP 204 No Content

Route Object

The Route entities defines rules to match client requests. Each Route is associated with a Service, and a Service may have multiple Routes associated to it. Every request matching a given Route will be proxied to its associated Service.

The combination of Routes and Services (and the separation of concerns between them) offers a powerful routing mechanism with which it is possible to define fine-grained entry-points in Kong leading to different upstream services of your infrastructure.

{
    "id": "22108377-8f26-4c0e-bd9e-2962c1d6b0e6",
    "created_at": 14888869056483,
    "updated_at": 14888869056483,
    "protocols": ["http", "https"],
    "methods": null,
    "hosts": ["example.com"],
    "paths": null,
    "regex_priority": 0,
    "strip_path": true,
    "preserve_host": false,
    "service": {
        "id": "4e13f54a-bbf1-47a8-8777-255fed7116f2"
    }
}


Add Route

Endpoints

/routes/

Request Body

Attributes Description
protocols
A list of the protocols this Route should allow. By default it is ["http", "https"], which means that the Route accepts both. When set to ["https"], HTTP requests are answered with a request to upgrade to HTTPS. With form-encoded, the notation is protocols[]=http&protocols[]=https. With JSON, use an Array.
methods
semi-optional
A list of HTTP methods that match this Route. For example: ["GET", "POST"]. At least one of hosts, paths, or methods must be set. With form-encoded, the notation is methods[]=GET&methods[]=OPTIONS. With JSON, use an Array.
hosts
semi-optional
A list of domain names that match this Route. For example: example.com. At least one of hosts, paths, or methods must be set. With form-encoded, the notation is hosts[]=foo.com&hosts[]=bar.com. With JSON, use an Array.
paths
semi-optional
A list of paths that match this Route. For example: /my-path. At least one of hosts, paths, or methods must be set. With form-encoded, the notation is paths[]=/foo&paths[]=/bar. With JSON, use an Array.
strip_path
optional
When matching a Route via one of the paths, strip the matching prefix from the upstream request URL. Defaults to true.
preserve_host
optional
When matching a Route via one of the hosts domain names, use the request Host header in the upstream request headers. By default set to false, and the upstream Host header will be that of the Service's host.
service The Service this Route is associated to. This is where the Route proxies traffic to. With form-encoded, the notation is service.id=<service_id>. With JSON, use "service":{"id":"<service_id>"}.

Response

HTTP 201 Created
{
    "id": "22108377-8f26-4c0e-bd9e-2962c1d6b0e6",
    "created_at": 14888869056483,
    "updated_at": 14888869056483,
    "protocols": ["http", "https"],
    "methods": null,
    "hosts": ["example.com"],
    "paths": null,
    "regex_priority": 0,
    "strip_path": true,
    "preserve_host": false,
    "service": {
        "id": "4e13f54a-bbf1-47a8-8777-255fed7116f2"
    }
}

Retrieve Route

Endpoints

/routes/{id}
Attributes Description
id
required
The id attribute of the Route to retrieve.

Response

HTTP 200 OK
{
    "id": "22108377-8f26-4c0e-bd9e-2962c1d6b0e6",
    "created_at": 14888869056483,
    "updated_at": 14888869056483,
    "protocols": ["http", "https"],
    "methods": null,
    "hosts": ["example.com"],
    "paths": null,
    "regex_priority": 0,
    "strip_path": true,
    "preserve_host": false,
    "service": {
        "id": "4e13f54a-bbf1-47a8-8777-255fed7116f2"
    }
}


List Routes

Endpoints

/routes

Request Querystring Parameters

Attributes Description
offset
optional
A cursor used for pagination. offset is an object identifier that defines a place in the list.
size
optional, default is 100 max is 1000
A limit on the number of objects to be returned per page.

Response

HTTP 200 OK
{
    "data": [{
      "id": "22108377-8f26-4c0e-bd9e-2962c1d6b0e6",
      "created_at": 14888869056483,
      "updated_at": 14888869056483,
      "protocols": ["http", "https"],
      "methods": null,
      "hosts": ["example.com"],
      "paths": null,
      "regex_priority": 0,
      "strip_path": true,
      "preserve_host": false,
      "service": {
          "id": "4e13f54a-bbf1-47a8-8777-255fed7116f2"
      }
    }, {
      "id": "8d9b862b-527c-4bf1-9786-bfbb728f6539",
      "created_at": 14888869056435,
      "updated_at": 14888869056435,
      "protocols": ["http"],
      "methods": ["GET"],
      "hosts": ["example.com"],
      "paths": ["/private"],
      "regex_priority": 0,
      "strip_path": true,
      "preserve_host": false,
      "service": {
          "id": "4e13f54a-bbf1-47a8-8777-255fed7116f2"
      }
    }],
    "next": "http://localhost:8001/services/foo/routes?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

List Routes associated to a Service

Endpoints

/services/{service name or id}/routes

Request Querystring Parameters

Attributes Description
service name or id
required
The id or the name attribute of the Service whose routes are to be Retrieved. When using this endpoint, only the Routes belonging to the specified Service will be listed.

Response

HTTP 200 OK
{
    "total": 10,
    "data": [{
      "id": "22108377-8f26-4c0e-bd9e-2962c1d6b0e6",
      "created_at": 14888869056483,
      "updated_at": 14888869056483,
      "protocols": ["http", "https"],
      "methods": null,
      "hosts": ["example.com"],
      "paths": null,
      "regex_priority": 0,
      "strip_path": true,
      "preserve_host": false,
      "service": {
          "id": "4e13f54a-bbf1-47a8-8777-255fed7116f2"
      }
    }, {
      "id": "8d9b862b-527c-4bf1-9786-bfbb728f6539",
      "created_at": 14888869056435,
      "updated_at": 14888869056435,
      "protocols": ["http"],
      "methods": ["GET"],
      "hosts": ["example.com"],
      "paths": ["/private"],
      "regex_priority": 0,
      "strip_path": true,
      "preserve_host": false,
      "service": {
          "id": "4e13f54a-bbf1-47a8-8777-255fed7116f2"
      }
    }],
    "next": "http://localhost:8001/services/foo/routes?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

Update Route

Endpoint

/routes/{id}
Attributes Description
id
required
The id attribute of the Route to update.

Request Body

Attributes Description
protocols
A list of the protocols this Route should allow. By default it is ["http", "https"], which means that the Route accepts both. When set to ["https"], HTTP requests are answered with a request to upgrade to HTTPS. With form-encoded, the notation is protocols[]=http&protocols[]=https. With JSON, use an Array.
methods
semi-optional
A list of HTTP methods that match this Route. For example: ["GET", "POST"]. At least one of hosts, paths, or methods must be set. With form-encoded, the notation is methods[]=GET&methods[]=OPTIONS. With JSON, use an Array.
hosts
semi-optional
A list of domain names that match this Route. For example: example.com. At least one of hosts, paths, or methods must be set. With form-encoded, the notation is hosts[]=foo.com&hosts[]=bar.com. With JSON, use an Array.
paths
semi-optional
A list of paths that match this Route. For example: /my-path. At least one of hosts, paths, or methods must be set. With form-encoded, the notation is paths[]=/foo&paths[]=/bar. With JSON, use an Array.
strip_path
optional
When matching a Route via one of the paths, strip the matching prefix from the upstream request URL. Defaults to true.
preserve_host
optional
When matching a Route via one of the hosts domain names, use the request Host header in the upstream request headers. By default set to false, and the upstream Host header will be that of the Service's host.
service The Service this Route is associated to. This is where the Route proxies traffic to. With form-encoded, the notation is service.id=<service_id>. With JSON, use "service":{"id":"<service_id>"}.

Response

HTTP 200 OK
{
    "id": "4e13f54a-bbf1-47a8-8777-255fed7116f2",
    "created_at": 1488869076800,
    "updated_at": 1488869076800,
    "connect_timeout": 60000,
    "protocol": "http",
    "host": "example.org",
    "port": 80,
    "path": "/api",
    "name": "example-service",
    "retries": 5,
    "read_timeout": 60000,
    "write_timeout": 60000
}


Delete Route

Endpoint

/routes/{id}
Attributes Description
id
required
The id attribute of the Route to delete.

Response

HTTP 204 No Content

API Object

Note: The API entity was deprecated in Kong 0.13.0.

It is strongly recommended to migrate your APIs to Routes and Services.

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 some combination of hosts, uris, and methods. Kong will proxy all requests to the API to the specified upstream URL.

{
    "created_at": 1488830759000,
    "hosts": [
        "example.org"
    ],
    "http_if_terminated": false,
    "https_only": false,
    "id": "6378122c-a0a1-438d-a5c6-efabae9fb969",
    "name": "example-api",
    "preserve_host": false,
    "retries": 5,
    "strip_uri": true,
    "upstream_connect_timeout": 60000,
    "upstream_read_timeout": 60000,
    "upstream_send_timeout": 60000,
    "upstream_url": "http://httpbin.org"
}

Add API

Endpoint

/apis/

Request Body

Attribute Description
name The API name.
hosts
semi-optional
A comma-separated list of domain names that point to your API. For example: example.com. At least one of hosts, uris, or methods should be specified.
uris
semi-optional
A comma-separated list of URIs prefixes that point to your API. For example: /my-path. At least one of hosts, uris, or methods should be specified.
methods
semi-optional
A comma-separated list of HTTP methods that point to your API. For example: GET,POST. At least one of hosts, uris, or methods should be specified.
upstream_url The base target URL that points to your API server. This URL will be used for proxying requests. For example: https://example.com.
strip_uri
optional
When matching an API via one of the uris prefixes, strip that matching prefix from the upstream URI to be requested. Default: true.
preserve_host
optional
When matching an API via one of the hosts domain names, make sure the request Host header is forwarded to the upstream service. By default, this is false, and the upstream Host header will be extracted from the configured upstream_url.
retries
optional
The number of retries to execute upon failure to proxy. The default is 5.
upstream_connect_timeout
optional
The timeout in milliseconds for establishing a connection to your upstream service. Defaults to 60000.
upstream_send_timeout
optional
The timeout in milliseconds between two successive write operations for transmitting a request to your upstream service Defaults to 60000.
upstream_read_timeout
optional
The timeout in milliseconds between two successive read operations for transmitting a request to your upstream service Defaults to 60000.
https_only
optional
To be enabled if you wish to only serve an API through HTTPS, on the appropriate port (8443 by default). Default: false.
http_if_terminated
optional
Consider the X-Forwarded-Proto header when enforcing HTTPS only traffic. Default: false.

Response

HTTP 201 Created
{
    "created_at": 1488830759000,
    "hosts": [
        "example.org"
    ],
    "http_if_terminated": false,
    "https_only": false,
    "id": "6378122c-a0a1-438d-a5c6-efabae9fb969",
    "name": "example-api",
    "preserve_host": false,
    "retries": 5,
    "strip_uri": true,
    "upstream_connect_timeout": 60000,
    "upstream_read_timeout": 60000,
    "upstream_send_timeout": 60000,
    "upstream_url": "http://httpbin.org"
}

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
{
    "created_at": 1488830759000,
    "hosts": [
        "example.org"
    ],
    "http_if_terminated": false,
    "https_only": false,
    "id": "6378122c-a0a1-438d-a5c6-efabae9fb969",
    "name": "example-api",
    "preserve_host": false,
    "retries": 5,
    "strip_uri": true,
    "upstream_connect_timeout": 60000,
    "upstream_read_timeout": 60000,
    "upstream_send_timeout": 60000,
    "upstream_url": "http://httpbin.org"
}

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.
upstream_url
optional
A filter on the list based on the apis upstream_url field.
retries
optional
A filter on the list based on the apis retries 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": [
        {
            "created_at": 1488830759000,
            "hosts": [
                "example.org"
            ],
            "http_if_terminated": false,
            "https_only": false,
            "id": "6378122c-a0a1-438d-a5c6-efabae9fb969",
            "name": "example-api",
            "preserve_host": false,
            "retries": 5,
            "strip_uri": true,
            "upstream_connect_timeout": 60000,
            "upstream_read_timeout": 60000,
            "upstream_send_timeout": 60000,
            "upstream_url": "http://httpbin.org"
        },
        {
            "created_at": 1488830708000,
            "hosts": [
                "api.com"
            ],
            "http_if_terminated": false,
            "https_only": false,
            "id": "0924978e-eb19-44a0-9adc-55f20db2f04d",
            "name": "my-api",
            "preserve_host": false,
            "retries": 10,
            "strip_uri": true,
            "upstream_connect_timeout": 1000,
            "upstream_read_timeout": 1000,
            "upstream_send_timeout": 1000,
            "upstream_url": "http://my-api.com"
        }
    ],
    "next": "http://localhost:8001/apis?size=2&offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

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 The API name.
hosts
semi-optional
A comma-separated list of domain names that point to your API. For example: example.com. At least one of hosts, uris, or methods should be specified.
uris
semi-optional
A comma-separated list of URIs prefixes that point to your API. For example: /my-path. At least one of hosts, uris, or methods should be specified.
methods
semi-optional
A comma-separated list of HTTP methods that point to your API. For example: GET,POST. At least one of hosts, uris, or methods should be specified.
upstream_url The base target URL that points to your API server. This URL will be used for proxying requests. For example: https://example.com.
strip_uri
optional
When matching an API via one of the uris prefixes, strip that matching prefix from the upstream URI to be requested. Default: true.
preserve_host
optional
When matching an API via one of the hosts domain names, make sure the request Host header is forwarded to the upstream service. By default, this is false, and the upstream Host header will be extracted from the configured upstream_url.
retries
optional
The number of retries to execute upon failure to proxy. The default is 5.
upstream_connect_timeout
optional
The timeout in milliseconds for establishing a connection to your upstream service. Defaults to 60000.
upstream_send_timeout
optional
The timeout in milliseconds between two successive write operations for transmitting a request to your upstream service Defaults to 60000.
upstream_read_timeout
optional
The timeout in milliseconds between two successive read operations for transmitting a request to your upstream service Defaults to 60000.
https_only
optional
To be enabled if you wish to only serve an API through HTTPS, on the appropriate port (8443 by default). Default: false.
http_if_terminated
optional
Consider the X-Forwarded-Proto header when enforcing HTTPS only traffic. Default: false.

Response

HTTP 200 OK
{
    "created_at": 1488830759000,
    "hosts": [
        "updated-example.org"
    ],
    "http_if_terminated": false,
    "https_only": false,
    "id": "6378122c-a0a1-438d-a5c6-efabae9fb969",
    "name": "my-updated-api",
    "preserve_host": false,
    "retries": 5,
    "strip_uri": true,
    "upstream_connect_timeout": 60000,
    "upstream_read_timeout": 60000,
    "upstream_send_timeout": 60000,
    "upstream_url": "http://httpbin.org"
}

Update Or Create API

Endpoint

/apis/

Request Body

Attribute Description
name The API name.
hosts
semi-optional
A comma-separated list of domain names that point to your API. For example: example.com. At least one of hosts, uris, or methods should be specified.
uris
semi-optional
A comma-separated list of URIs prefixes that point to your API. For example: /my-path. At least one of hosts, uris, or methods should be specified.
methods
semi-optional
A comma-separated list of HTTP methods that point to your API. For example: GET,POST. At least one of hosts, uris, or methods should be specified.
upstream_url The base target URL that points to your API server. This URL will be used for proxying requests. For example: https://example.com.
strip_uri
optional
When matching an API via one of the uris prefixes, strip that matching prefix from the upstream URI to be requested. Default: true.
preserve_host
optional
When matching an API via one of the hosts domain names, make sure the request Host header is forwarded to the upstream service. By default, this is false, and the upstream Host header will be extracted from the configured upstream_url.
retries
optional
The number of retries to execute upon failure to proxy. The default is 5.
upstream_connect_timeout
optional
The timeout in milliseconds for establishing a connection to your upstream service. Defaults to 60000.
upstream_send_timeout
optional
The timeout in milliseconds between two successive write operations for transmitting a request to your upstream service Defaults to 60000.
upstream_read_timeout
optional
The timeout in milliseconds between two successive read operations for transmitting a request to your upstream service Defaults to 60000.
https_only
optional
To be enabled if you wish to only serve an API through HTTPS, on the appropriate port (8443 by default). Default: false.
http_if_terminated
optional
Consider the X-Forwarded-Proto header when enforcing HTTPS only traffic. Default: false.

The behavior of PUT endpoints is the following: if the request payload does not contain an entity's primary key (id for APIs), the entity will be created with the given payload. If the request payload does contain an entity's primary key, the payload will "replace" the entity specified by the given primary key. If the primary key is not that of an existing entity, 404 NOT FOUND will be returned.

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 a Service. 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"
}

Create Consumer

Endpoint

/consumers/

Request Form Parameters

Attributes Description
username
semi-optional
The unique 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 unique 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": 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"
}

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 unique 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 unique 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 unique 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 unique 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 behavior of PUT endpoints is the following: if the request payload does not contain an entity's primary key (id for Consumers), the entity will be created with the given payload. If the request payload does contain an entity's primary key, the payload will "replace" the entity specified by the given primary key. If the primary key is not that of an existing entity, 404 NOT FOUND will be returned.

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 Object

A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. It is how you can add functionalities to Services 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 Plugins Gallery.

When adding a Plugin Configuration to a Service, every request made by a client to that Service will run said Plugin. If a Plugin needs to be tuned to different values for some specific Consumers, you can do so by specifying the consumer_id value:

{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "service_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
}

See the Precedence section below for more details.

Precedence

A plugin will always be run once and only once per request. But the configuration with which it will run depends on the entities it has been configured for.

Plugins can be configured for various entities, combination of entities, or even globally. This is useful, for example, when you wish to configure a plugin a certain way for most requests, but make authenticated requests behave slightly differently.

Therefore, there exists an order of precedence for running a plugin when it has been applied to different entities with different configurations. The rule of thumb is: the more specific a plugin is with regards to how many entities it has been configured on, the higher its priority.

The complete order of precedence when a plugin has been configured multiple times is:

  1. Plugins configured on a combination of: a Route, a Service, and a Consumer. (Consumer means the request must be authenticated).
  2. Plugins configured on a combination of a Route and a Consumer. (Consumer means the request must be authenticated).
  3. Plugins configured on a combination of a Service and a Consumer. (Consumer means the request must be authenticated).
  4. Plugins configured on a combination of a Route and a Service.
  5. Plugins configured on a Consumer. (Consumer means the request must be authenticated).
  6. Plugins configured on a Route.
  7. Plugins configured on a Service.
  8. Plugins configured to run globally.

Example: if the rate-limiting plugin is applied twice (with different configurations): for a Service (Plugin config A), and for a Consumer (Plugin config B), then requests authenticating this Consumer will run Plugin config B and ignore A. However, requests that do not authenticate this Consumer will fallback to running Plugin config A. Note that if config B is disabled (its enabled flag is set to false), config A will apply to requests that would have otherwise matched config B.


Add Plugin

You can add a plugin in four different ways:

  • For every Service/Route and Consumer. Don't set consumer_id and set service_id or route_id.
  • For every Service/Route and a specific Consumer. Only set consumer_id.
  • For every Consumer and a specific Service. Only set service_id (warning: some plugins only allow setting their route_id)
  • For every Consumer and a specific Route. Only set route_id (warning: some plugins only allow setting their service_id)
  • For a specific Service/Route and Consumer. Set both service_id/route_id and consumer_id.

Note that not all plugins allow to specify consumer_id. Check the plugin documentation.

Endpoint

/plugins/

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.
config.{property} The configuration properties for the Plugin which can be found on the plugins documentation page in the Plugin Gallery.
enabled Whether the plugin is applied. Default: true.

Response

HTTP 201 Created
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "service_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
}

Retrieve Plugin

/plugins/{id}

Request Querystring Parameters

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

Response

HTTP 200 OK
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "service_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
}

List All Plugins

Endpoint

/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.
service_id
optional
A filter on the list based on the service_id field.
route_id
optional
A filter on the list based on the route_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",
          "service_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",
          "service_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"
}

Update Plugin

Endpoint

/plugins/{plugin id}
Attributes Description
plugin id
required
The unique identifier of the plugin configuration to update

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.
config.{property} The configuration properties for the Plugin which can be found on the plugins documentation page in the Plugin Gallery.
enabled Whether the plugin is applied. Default: true.

Response

HTTP 200 OK
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "service_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
}

Update or Add Plugin

Endpoint

/plugins/

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.
config.{property} The configuration properties for the Plugin which can be found on the plugins documentation page in the Plugin Gallery.
enabled Whether the plugin is applied. Default: true.

The behavior of PUT endpoints is the following: if the request payload does not contain an entity's primary key (id and name for Plugins), the entity will be created with the given payload. If the request payload does contain an entity's primary key, the payload will "replace" the entity specified by the given primary key. If the primary key is not that of an existing entity, 404 NOT FOUND will be returned.

Response

HTTP 201 Created or HTTP 200 OK

See POST and PATCH responses.


Delete Plugin

Endpoint

/plugins/{plugin id}
Attributes Description
plugin id
required
The unique identifier of the plugin configuration to delete

Response

HTTP 204 No Content

Retrieve Enabled Plugins

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

Endpoint

/plugins/enabled

Response

HTTP 200 OK
{
    "enabled_plugins": [
        "jwt",
        "acl",
        "cors",
        "oauth2",
        "tcp-log",
        "udp-log",
        "file-log",
        "http-log",
        "key-auth",
        "hmac-auth",
        "basic-auth",
        "ip-restriction",
        "request-transformer",
        "response-transformer",
        "request-size-limiting",
        "rate-limiting",
        "response-ratelimiting",
        "aws-lambda",
        "bot-detection",
        "correlation-id",
        "datadog",
        "galileo",
        "ldap-auth",
        "loggly",
        "runscope",
        "statsd",
        "syslog"
    ]
}

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

Certificate Object

A certificate object represents a public certificate/private key pair for an SSL certificate. These objects are used by Kong to handle SSL/TLS termination for encrypted requests. Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames.

{
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----..."
}

Add Certificate

Endpoint

/certificates/

Request Body

Attributes Description
cert PEM-encoded public certificate of the SSL key pair.
key PEM-encoded private key of the SSL key pair.
snis
optional
One or more hostnames to associate with this certificate as an SNI. This is a sugar parameter that will, under the hood, create an SNI object and associate it with this certificate for your convenience.

Response

HTTP 201 Created
{
    "id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "snis": [
        "example.com"
    ],
    "created_at": 1485521710265
}

Retrieve Certificate

Endpoint

/certificates/{sni or id}
Attributes Description
SNI or id
required
The unique identifier or an SNI name associated with this certificate.

Response

HTTP 200 OK
{
    "id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "snis": [
        "example.com"
    ],
    "created_at": 1485521710265
}

List Certificates

Endpoint

/certificates/

Response

HTTP 200 OK
{
    "total": 2,
    "data": [
        {
            "id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
            "cert": "-----BEGIN CERTIFICATE-----...",
            "key": "-----BEGIN RSA PRIVATE KEY-----...",
            "snis": [
                "example.com"
            ],
            "created_at": 1485521710265
        },
        {
            "id": "6b5b6f71-c0b3-426d-8f3b-8de2c67c816b",
            "cert": "-----BEGIN CERTIFICATE-----...",
            "key": "-----BEGIN RSA PRIVATE KEY-----...",
            "snis": [
                "example.org"
            ],
            "created_at": 1485522651185
        }
    ]
}

Update Certificate

/certificates/{sni or id}
Attributes Description
SNI or id
required
The unique identifier or an SNI name associated with this certificate.

Request Body

Attributes Description
cert PEM-encoded public certificate of the SSL key pair.
key PEM-encoded private key of the SSL key pair.
snis
optional
One or more hostnames to associate with this certificate as an SNI. This is a sugar parameter that will, under the hood, create an SNI object and associate it with this certificate for your convenience.

Response

HTTP 200 OK
{
    "id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "snis": [
        "example.com"
    ],
    "created_at": 1485521710265
}

Update or Create Certificate

Endpoint

/certificates/

Request Body

Attributes Description
cert PEM-encoded public certificate of the SSL key pair.
key PEM-encoded private key of the SSL key pair.
snis
optional
One or more hostnames to associate with this certificate as an SNI. This is a sugar parameter that will, under the hood, create an SNI object and associate it with this certificate for your convenience.

The behavior of PUT endpoints is the following: if the request payload does not contain an entity's primary key (id for Certificates), the entity will be created with the given payload. If the request payload does contain an entity's primary key, the payload will "replace" the entity specified by the given primary key. If the primary key is not that of an existing entity, 404 NOT FOUND will be returned.

Response

HTTP 201 Created or HTTP 200 OK

See POST and PATCH responses.


Delete Certificate

/certificates/{sni or id}
Attributes Description
sni or id
required
The unique identifier or an SNI name associated with this certificate.

Response

HTTP 204 No Content

SNI Objects

An SNI object represents a many-to-one mapping of hostnames to a certificate. That is, a certificate object can have many hostnames associated with it; when Kong receives an SSL request, it uses the SNI field in the Client Hello to lookup the certificate object based on the SNI associated with the certificate.

{
    "name": "example.com",
    "ssl_certificate_id": "21b69eab-09d9-40f9-a55e-c4ee47fada68"
}

Add SNI

Endpoint

/snis/

Request Body

Attributes Description
name The SNI name to associate with the given certificate.
ssl_certificate_id The id (a UUID) of the certificate with which to associate the SNI hostname.

Response

HTTP 201 Created
{
    "name": "example.com",
    "ssl_certificate_id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
    "created_at": 1485521710265
}

Retrieve SNI

Endpoint

/snis/{name}
Attributes Description
name
required
The name of the SNI object.

Response

HTTP 200 OK
{
    "name": "example.com",
    "ssl_certificate_id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
    "created_at": 1485521710265
}

List SNIs

Endpoint

/snis/

Response

HTTP 200 OK
{
    "total": 2,
    "data": [
        {
            "name": "example.com",
            "ssl_certificate_id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
            "created_at": 1485521710265
        },
        {
            "name": "example.org",
            "ssl_certificate_id": "6b5b6f71-c0b3-426d-8f3b-8de2c67c816b",
            "created_at": 1485521710265
        }
    ]
}

Update SNI

/snis/{name}
Attributes Description
name
required
The name of the SNI object.

Response

HTTP 200 OK
{
    "name": "example.com",
    "ssl_certificate_id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
    "created_at": 1485521710265
}

Update or Create SNI

Endpoint

/snis/

Request Body

Attributes Description
name The SNI name to associate with the given certificate.
ssl_certificate_id The id (a UUID) of the certificate with which to associate the SNI hostname.

The behavior of PUT endpoints is the following: if the request payload does not contain an entity's primary key (name for SNIs), the entity will be created with the given payload. If the request payload does contain an entity's primary key, the payload will "replace" the entity specified by the given primary key. If the primary key is not that of an existing entity, 404 NOT FOUND will be returned.

Response

HTTP 201 Created or HTTP 200 OK

See POST and PATCH responses.


Delete SNI

/snis/{name}
Attributes Description
name
required
The name of the SNI object.

Response

HTTP 204 No Content

Upstream Objects

The upstream object represents a virtual hostname and can be used to loadbalance incoming requests over multiple services (targets). So for example an upstream named service.v1.xyz for a Service object whose host is service.v1.xyz. Requests for this Service would be proxied to the targets defined within the upstream.

An upstream also includes a health checker, which is able to enable and disable targets based on their ability or inability to serve requests. The configuration for the health checker is stored in the upstream object, and applies to all of its targets.

{
    "name": "service.v1.xyz",
    "hash_on": "none",
    "hash_fallback": "none",
    "healthchecks": {
        "active": {
            "concurrency": 10,
            "healthy": {
                "http_statuses": [ 200, 302 ],
                "interval": 0,
                "successes": 0
            },
            "http_path": "/",
            "timeout": 1,
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [ 429, 404, 500, 501,
                                   502, 503, 504, 505 ],
                "interval": 0,
                "tcp_failures": 0,
                "timeouts": 0
            }
        },
        "passive": {
            "healthy": {
                "http_statuses": [ 200, 201, 202, 203,
                                   204, 205, 206, 207,
                                   208, 226, 300, 301,
                                   302, 303, 304, 305,
                                   306, 307, 308 ],
                "successes": 0
            },
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [ 429, 500, 503 ],
                "tcp_failures": 0,
                "timeouts": 0
            }
        }
    },
    "slots": 10
}

Add upstream

Endpoint

/upstreams/

Request Body

Attributes Description
name This is a hostname, which must be equal to the host of a Service.
slots
optional
The number of slots in the loadbalancer algorithm (10-65536, defaults to 1000).
hash_on
optional
What to use as hashing input: none, consumer, ip, or header (defaults to none resulting in a weighted-round-robin scheme).
hash_fallback
optional
What to use as hashing input if the primary hash_on does not return a hash (eg. header is missing, or no consumer identified): none, consumer, ip, or header (defaults to none).
hash_on_header
semi-optional
The header name to take the value from as hash input (only required when hash_on is set to header).
hash_fallback_header
semi-optional
The header name to take the value from as hash input (only required when hash_fallback is set to header).
healthchecks.active.timeout
optional
Socket timeout for active health checks (in seconds).
healthchecks.active.concurrency
optional
Number of targets to check concurrently in active health checks.
healthchecks.active.http_path
optional
Path to use in GET HTTP request to run as a probe on active health checks.
healthchecks.active.healthy.interval
optional
Interval between active health checks for healthy targets (in seconds). A value of zero indicates that active probes for healthy targets should not be performed.
healthchecks.active.healthy.http_statuses
optional
An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks.
healthchecks.active.healthy.successes
optional
Number of successes in active probes (as defined by healthchecks.active.healthy.http_statuses) to consider a target healthy.
healthchecks.active.unhealthy.interval
optional
Interval between active health checks for unhealthy targets (in seconds). A value of zero indicates that active probes for unhealthy targets should not be performed.
healthchecks.active.unhealthy.http_statuses
optional
An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks.
healthchecks.active.unhealthy.tcp_failures
optional
Number of TCP failures in active probes to consider a target unhealthy.
healthchecks.active.unhealthy.timeouts
optional
Number of timeouts in active probes to consider a target unhealthy.
healthchecks.active.unhealthy.http_failures
optional
Number of HTTP failures in active probes (as defined by healthchecks.active.unhealthy.http_statuses) to consider a target unhealthy.
healthchecks.passive.healthy.http_statuses
optional
An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks.
healthchecks.passive.healthy.successes
optional
Number of successes in proxied traffic (as defined by healthchecks.passive.healthy.http_statuses) to consider a target healthy, as observed by passive health checks.
healthchecks.passive.unhealthy.http_statuses
optional
An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks.
healthchecks.passive.unhealthy.tcp_failures
optional
Number of TCP failures in proxied traffic to consider a target unhealthy, as observed by passive health checks.
healthchecks.passive.unhealthy.timeouts
optional
Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks.
healthchecks.passive.unhealthy.http_failures
optional
Number of HTTP failures in proxied traffic (as defined by healthchecks.passive.unhealthy.http_statuses) to consider a target unhealthy, as observed by passive health checks.

Response

HTTP 201 Created
{
    "id": "13611da7-703f-44f8-b790-fc1e7bf51b3e",
    "name": "service.v1.xyz",
    "hash_on": "none",
    "hash_fallback": "none",
    "healthchecks": {
        "active": {
            "concurrency": 10,
            "healthy": {
                "http_statuses": [ 200, 302 ],
                "interval": 0,
                "successes": 0
            },
            "http_path": "/",
            "timeout": 1,
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [ 429, 404, 500, 501,
                                   502, 503, 504, 505 ],
                "interval": 0,
                "tcp_failures": 0,
                "timeouts": 0
            }
        },
        "passive": {
            "healthy": {
                "http_statuses": [ 200, 201, 202, 203,
                                   204, 205, 206, 207,
                                   208, 226, 300, 301,
                                   302, 303, 304, 305,
                                   306, 307, 308 ],
                "successes": 0
            },
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [ 429, 500, 503 ],
                "tcp_failures": 0,
                "timeouts": 0
            }
        }
    },
    "slots": 10,
    "created_at": 1485521710265
}

Retrieve upstream

Endpoint

/upstreams/{name or id}
Attributes Description
name or id
required
The unique identifier or the name of the upstream to retrieve

Response

HTTP 200 OK
{
    "id": "13611da7-703f-44f8-b790-fc1e7bf51b3e",
    "name": "service.v1.xyz",
    "hash_on": "none",
    "hash_fallback": "none",
    "healthchecks": {
        "active": {
            "concurrency": 10,
            "healthy": {
                "http_statuses": [ 200, 302 ],
                "interval": 0,
                "successes": 0
            },
            "http_path": "/",
            "timeout": 1,
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [ 429, 404, 500, 501,
                                   502, 503, 504, 505 ],
                "interval": 0,
                "tcp_failures": 0,
                "timeouts": 0
            }
        },
        "passive": {
            "healthy": {
                "http_statuses": [ 200, 201, 202, 203,
                                   204, 205, 206, 207,
                                   208, 226, 300, 301,
                                   302, 303, 304, 305,
                                   306, 307, 308 ],
                "successes": 0
            },
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [ 429, 500, 503 ],
                "tcp_failures": 0,
                "timeouts": 0
            }
        }
    },
    "slots": 10,
    "created_at": 1485521710265
}

List upstreams

Endpoint

/upstreams/

Request Querystring Parameters

Attributes Description
id
optional
A filter on the list based on the upstream id field.
name
optional
A filter on the list based on the upstream name field.
hash_on
optional
A filter on the list based on the upstream hash_on field.
hash_fallback
optional
A filter on the list based on the upstream hash_fallback field.
hash_on_header
optional
A filter on the list based on the upstream hash_on_header field.
hash_fallback_header
optional
A filter on the list based on the upstream hash_fallback_header field.
slots
optional
A filter on the list based on the upstream slots 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": 3,
    "data": [
        {
            "created_at": 1485521710265,
            "id": "13611da7-703f-44f8-b790-fc1e7bf51b3e",
            "name": "service.v1.xyz",
            "hash_on": "none",
            "hash_fallback": "none",
            "healthchecks": {
                "active": {
                    "concurrency": 10,
                    "healthy": {
                        "http_statuses": [ 200, 302 ],
                        "interval": 0,
                        "successes": 0
                    },
                    "http_path": "/",
                    "timeout": 1,
                    "unhealthy": {
                        "http_failures": 0,
                        "http_statuses": [ 429, 404, 500, 501,
                                           502, 503, 504, 505 ],
                        "interval": 0,
                        "tcp_failures": 0,
                        "timeouts": 0
                    }
                },
                "passive": {
                    "healthy": {
                        "http_statuses": [ 200, 201, 202, 203,
                                           204, 205, 206, 207,
                                           208, 226, 300, 301,
                                           302, 303, 304, 305,
                                           306, 307, 308 ],
                        "successes": 0
                    },
                    "unhealthy": {
                        "http_failures": 0,
                        "http_statuses": [ 429, 500, 503 ],
                        "tcp_failures": 0,
                        "timeouts": 0
                    }
                }
            },
            "slots": 10
        },
        {
            "created_at": 1485522651185,
            "id": "07131005-ba30-4204-a29f-0927d53257b4",
            "name": "service.v2.xyz",
            "hash_on": "none",
            "hash_fallback": "none",
            "healthchecks": {
                "active": {
                    "concurrency": 10,
                    "healthy": {
                        "http_statuses": [ 200, 302 ],
                        "interval": 5,
                        "successes": 2
                    },
                    "http_path": "/health_status",
                    "timeout": 1,
                    "unhealthy": {
                        "http_failures": 5,
                        "http_statuses": [ 429, 404, 500, 501,
                                           502, 503, 504, 505 ],
                        "interval": 5,
                        "tcp_failures": 2,
                        "timeouts": 3
                    }
                },
                "passive": {
                    "healthy": {
                        "http_statuses": [ 200, 201, 202, 203,
                                           204, 205, 206, 207,
                                           208, 226, 300, 301,
                                           302, 303, 304, 305,
                                           306, 307, 308 ],
                        "successes": 5
                    },
                    "unhealthy": {
                        "http_failures": 5,
                        "http_statuses": [ 429, 500, 503 ],
                        "tcp_failures": 2,
                        "timeouts": 7
                    }
                }
            },
            "slots": 10
        }
    ],
    "next": "http://localhost:8001/upstreams?size=2&offset=Mg%3D%3D",
    "offset": "Mg=="
}

Update upstream

Endpoint

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

Request Body

Attributes Description
name This is a hostname, which must be equal to the host of a Service.
slots
optional
The number of slots in the loadbalancer algorithm (10-65536, defaults to 1000).
hash_on
optional
What to use as hashing input: none, consumer, ip, or header (defaults to none resulting in a weighted-round-robin scheme).
hash_fallback
optional
What to use as hashing input if the primary hash_on does not return a hash (eg. header is missing, or no consumer identified): none, consumer, ip, or header (defaults to none).
hash_on_header
semi-optional
The header name to take the value from as hash input (only required when hash_on is set to header).
hash_fallback_header
semi-optional
The header name to take the value from as hash input (only required when hash_fallback is set to header).
healthchecks.active.timeout
optional
Socket timeout for active health checks (in seconds).
healthchecks.active.concurrency
optional
Number of targets to check concurrently in active health checks.
healthchecks.active.http_path
optional
Path to use in GET HTTP request to run as a probe on active health checks.
healthchecks.active.healthy.interval
optional
Interval between active health checks for healthy targets (in seconds). A value of zero indicates that active probes for healthy targets should not be performed.
healthchecks.active.healthy.http_statuses
optional
An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks.
healthchecks.active.healthy.successes
optional
Number of successes in active probes (as defined by healthchecks.active.healthy.http_statuses) to consider a target healthy.
healthchecks.active.unhealthy.interval
optional
Interval between active health checks for unhealthy targets (in seconds). A value of zero indicates that active probes for unhealthy targets should not be performed.
healthchecks.active.unhealthy.http_statuses
optional
An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks.
healthchecks.active.unhealthy.tcp_failures
optional
Number of TCP failures in active probes to consider a target unhealthy.
healthchecks.active.unhealthy.timeouts
optional
Number of timeouts in active probes to consider a target unhealthy.
healthchecks.active.unhealthy.http_failures
optional
Number of HTTP failures in active probes (as defined by healthchecks.active.unhealthy.http_statuses) to consider a target unhealthy.
healthchecks.passive.healthy.http_statuses
optional
An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks.
healthchecks.passive.healthy.successes
optional
Number of successes in proxied traffic (as defined by healthchecks.passive.healthy.http_statuses) to consider a target healthy, as observed by passive health checks.
healthchecks.passive.unhealthy.http_statuses
optional
An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks.
healthchecks.passive.unhealthy.tcp_failures
optional
Number of TCP failures in proxied traffic to consider a target unhealthy, as observed by passive health checks.
healthchecks.passive.unhealthy.timeouts
optional
Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks.
healthchecks.passive.unhealthy.http_failures
optional
Number of HTTP failures in proxied traffic (as defined by healthchecks.passive.unhealthy.http_statuses) to consider a target unhealthy, as observed by passive health checks.

Response

HTTP 200 OK
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "name": "service.v1.xyz",
    "hash_on": "none",
    "hash_fallback": "none",
    "slots": 10,
    "healthchecks": {
        "active": {
            "concurrency": 10,
            "healthy": {
                "http_statuses": [ 200, 302 ],
                "interval": 0,
                "successes": 0
            },
            "http_path": "/",
            "timeout": 1,
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [ 429, 404, 500, 501,
                                   502, 503, 504, 505 ],
                "interval": 0,
                "tcp_failures": 0,
                "timeouts": 0
            }
        },
        "passive": {
            "healthy": {
                "http_statuses": [ 200, 201, 202, 203,
                                   204, 205, 206, 207,
                                   208, 226, 300, 301,
                                   302, 303, 304, 305,
                                   306, 307, 308 ],
                "successes": 0
            },
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [ 429, 500, 503 ],
                "tcp_failures": 0,
                "timeouts": 0
            }
        }
    },
    "created_at": 1422386534
}

Update Or create Upstream

Endpoint

/upstreams/

Request Body

Attributes Description
name This is a hostname, which must be equal to the host of a Service.
slots
optional
The number of slots in the loadbalancer algorithm (10-65536, defaults to 1000).
hash_on
optional
What to use as hashing input: none, consumer, ip, or header (defaults to none resulting in a weighted-round-robin scheme).
hash_fallback
optional
What to use as hashing input if the primary hash_on does not return a hash (eg. header is missing, or no consumer identified): none, consumer, ip, or header (defaults to none).
hash_on_header
semi-optional
The header name to take the value from as hash input (only required when hash_on is set to header).
hash_fallback_header
semi-optional
The header name to take the value from as hash input (only required when hash_fallback is set to header).
healthchecks.active.timeout
optional
Socket timeout for active health checks (in seconds).
healthchecks.active.concurrency
optional
Number of targets to check concurrently in active health checks.
healthchecks.active.http_path
optional
Path to use in GET HTTP request to run as a probe on active health checks.
healthchecks.active.healthy.interval
optional
Interval between active health checks for healthy targets (in seconds). A value of zero indicates that active probes for healthy targets should not be performed.
healthchecks.active.healthy.http_statuses
optional
An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks.
healthchecks.active.healthy.successes
optional
Number of successes in active probes (as defined by healthchecks.active.healthy.http_statuses) to consider a target healthy.
healthchecks.active.unhealthy.interval
optional
Interval between active health checks for unhealthy targets (in seconds). A value of zero indicates that active probes for unhealthy targets should not be performed.
healthchecks.active.unhealthy.http_statuses
optional
An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks.
healthchecks.active.unhealthy.tcp_failures
optional
Number of TCP failures in active probes to consider a target unhealthy.
healthchecks.active.unhealthy.timeouts
optional
Number of timeouts in active probes to consider a target unhealthy.
healthchecks.active.unhealthy.http_failures
optional
Number of HTTP failures in active probes (as defined by healthchecks.active.unhealthy.http_statuses) to consider a target unhealthy.
healthchecks.passive.healthy.http_statuses
optional
An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks.
healthchecks.passive.healthy.successes
optional
Number of successes in proxied traffic (as defined by healthchecks.passive.healthy.http_statuses) to consider a target healthy, as observed by passive health checks.
healthchecks.passive.unhealthy.http_statuses
optional
An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks.
healthchecks.passive.unhealthy.tcp_failures
optional
Number of TCP failures in proxied traffic to consider a target unhealthy, as observed by passive health checks.
healthchecks.passive.unhealthy.timeouts
optional
Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks.
healthchecks.passive.unhealthy.http_failures
optional
Number of HTTP failures in proxied traffic (as defined by healthchecks.passive.unhealthy.http_statuses) to consider a target unhealthy, as observed by passive health checks.

The behavior of PUT endpoints is the following: if the request payload does not contain an entity's primary key (id for Upstreams), the entity will be created with the given payload. If the request payload does contain an entity's primary key, the payload will "replace" the entity specified by the given primary key. If the primary key is not that of an existing entity, 404 NOT FOUND will be returned.

Response

HTTP 201 Created or HTTP 200 OK

See POST and PATCH responses.


Delete upstream

Endpoint

/upstreams/{name or id}
Attributes Description
name or id
required
The unique identifier or the name of the upstream to delete

Response

HTTP 204 No Content

Show Upstream health for node

Displays the health status for all Targets of a given Upstream, according to the perspective of a specific Kong node. Note that, being node-specific information, making this same request to different nodes of the Kong cluster may produce different results. For example, one specific node of the Kong cluster may be experiencing network issues, causing it to fail to connect to some Targets: these Targets will be marked as unhealthy by that node (directing traffic from this node to other Targets that it can successfully reach), but healthy to all others Kong nodes (which have no problems using that Target).

The data field of the response contains an array of Target objects. The health for each Target is returned in its health field:

  • If a Target fails to be activated in the ring balancer due to DNS issues, its status displays as DNS_ERROR.
  • When health checks are not enabled in the Upstream configuration, the health status for active Targets is displayed as HEALTHCHECKS_OFF.
  • When health checks are enabled and the Target is determined to be healthy, either automatically or manually, its status is displayed as HEALTHY. This means that this Target is currently included in this Upstream's load balancer ring.
  • When a Target has been disabled by either active or passive health checks (circuit breakers) or manually, its status is displayed as UNHEALTHY. The load balancer is not directing any traffic to this Target via this Upstream.

Endpoint

/upstreams/{name or id}/health/
Attributes Description
name or id
required
The unique identifier or the name of the Upstream for which to display Target health.

Response

HTTP 200 OK
{
    "total": 2,
    "node_id": "cbb297c0-14a9-46bc-ad91-1d0ef9b42df9",
    "data": [
        {
            "created_at": 1485524883980,
            "id": "18c0ad90-f942-4098-88db-bbee3e43b27f",
            "health": "HEALTHY",
            "target": "127.0.0.1:20000",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 100
        },
        {
            "created_at": 1485524914883,
            "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890",
            "health": "UNHEALTHY",
            "target": "127.0.0.1:20002",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 200
        }
    ]
}

Target Object

A target is an ip address/hostname with a port that identifies an instance of a backend service. Every upstream can have many targets, and the targets can be dynamically added. Changes are effectuated on the fly.

Because the upstream maintains a history of target changes, the targets cannot be deleted or modified. To disable a target, post a new one with weight=0; alternatively, use the DELETE convenience method to accomplish the same.

The current target object definition is the one with the latest created_at.

{
    "target": "1.2.3.4:80",
    "weight": 15,
    "upstream_id": "ee3310c1-6789-40ac-9386-f79c0cb58432"
}

Add target

Endpoint

/upstreams/{name or id}/targets
Attributes Description
name or id
required
The unique identifier or the name of the upstream to which to add the target

Request Body

Attributes Description
target The target address (ip or hostname) and port. If omitted the port defaults to 8000. If the hostname resolves to an SRV record, the port value will overridden by the value from the dns record.
weight
optional
The weight this target gets within the upstream loadbalancer (0-1000, defaults to 100). If the hostname resolves to an SRV record, the weight value will overridden by the value from the dns record.

Response

HTTP 201 Created
{
    "id": "4661f55e-95c2-4011-8fd6-c5c56df1c9db",
    "target": "1.2.3.4:80",
    "weight": 15,
    "upstream_id": "ee3310c1-6789-40ac-9386-f79c0cb58432",
    "created_at": 1485523507446
}

List targets

Lists all targets currently active on the upstream's load balancing wheel.

Note: The behavior of this endpoint changed in the 0.12.0 release from returning all targets belonging to an upstream, to only currently active ones. The endpoint returning the entire history of targets was moved to [List all targets](#list-all-targets).

Endpoint

/upstreams/{name or id}/targets
Attributes Description
name or id
required
The unique identifier or the name of the upstream for which to list the targets

Request Querystring Parameters

Attributes Description
id
optional
A filter on the list based on the target id field.
target
optional
A filter on the list based on the target target field.
weight
optional
A filter on the list based on the target weight 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": 30,
    "data": [
        {
            "created_at": 1485524883980,
            "id": "18c0ad90-f942-4098-88db-bbee3e43b27f",
            "target": "127.0.0.1:20000",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 100
        },
        {
            "created_at": 1485524897232,
            "id": "9b96f13d-65af-4f30-bbe9-b367121dd26b",
            "target": "127.0.0.1:20001",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 0
        },
        {
            "created_at": 1485524914883,
            "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890",
            "target": "127.0.0.1:20002",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 200
        }
    ]
}

List all targets

Lists all targets of the upstream. Multiple target objects for the same target may be returned, showing the history of changes for a specific target. The target object with the latest created_at is the current definition.

Note: This endpoint is only available with Kong 0.12.0+

Endpoint

/upstreams/{name or id}/targets/all/
Attributes Description
name or id
required
The unique identifier or the name of the upstream for which to list the targets.

Response

HTTP 200 OK
{
    "total": 2,
    "data": [
        {
            "created_at": 1485524883980,
            "id": "18c0ad90-f942-4098-88db-bbee3e43b27f",
            "target": "127.0.0.1:20000",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 100
        },
        {
            "created_at": 1485524914883,
            "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890",
            "target": "127.0.0.1:20002",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 200
        }
    ]
}

Delete target

Disable a target in the load balancer. Under the hood, this method creates a new entry for the given target definition with a weight of 0.

Note: This endpoint is only available with Kong 0.10.1+

Endpoint

/upstreams/{upstream name or id}/targets/{target or id}
Attributes Description
upstream name or id
required
The unique identifier or the name of the upstream for which to delete the target.
target or id
required
The host/port combination element of the target to remove, or the id of an existing target entry.

Response

HTTP 204 No Content

Set target as healthy

Set the current health status of a target in the load balancer to "healthy" in the entire Kong cluster.

This endpoint can be used to manually re-enable a target that was previously disabled by the upstream's health checker. Upstreams only forward requests to healthy nodes, so this call tells Kong to start using this target again.

This resets the health counters of the health checkers running in all workers of the Kong node, and broadcasts a cluster-wide message so that the "healthy" status is propagated to the whole Kong cluster.

Endpoint

/upstreams/{upstream name or id}/targets/{target or id}/healthy
Attributes Description
upstream name or id
required
The unique identifier or the name of the upstream.
target or id
required
The host/port combination element of the target to set as healthy, or the id of an existing target entry.

Response

HTTP 204 No Content

Set target as unhealthy

Set the current health status of a target in the load balancer to "unhealthy" in the entire Kong cluster.

This endpoint can be used to manually disable a target and have it stop responding to requests. Upstreams only forward requests to healthy nodes, so this call tells Kong to start skipping this target in the ring-balancer algorithm.

This call resets the health counters of the health checkers running in all workers of the Kong node, and broadcasts a cluster-wide message so that the "unhealthy" status is propagated to the whole Kong cluster.

Active health checks continue to execute for unhealthy targets. Note that if active health checks are enabled and the probe detects that the target is actually healthy, it will automatically re-enable it again. To permanently remove a target from the ring-balancer, you should delete a target instead.

Endpoint

/upstreams/{upstream name or id}/targets/{target or id}/unhealthy
Attributes Description
upstream name or id
required
The unique identifier or the name of the upstream.
target or id
required
The host/port combination element of the target to set as unhealthy, or the id of an existing target entry.

Response

HTTP 204 No Content

Keep up with the latest features