Skip to content
|
You are browsing the Kong Gateway documentation archive. This documentation is no longer actively maintained.
See the latest Kong Gateway documentation.
Kong Gateway OSS [ARCHIVE]
0.13.x

PermalinkAdmin API

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

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

PermalinkInformation routes

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

PermalinkRetrieve node status

Retrieve usage information about a node, with some basic information about the connections being processed by the underlying nginx process, and the 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.

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

PermalinkAdd Service

Endpoint

/services/

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

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

PermalinkList Services

Endpoint

/services/

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

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

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

PermalinkDelete 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

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

PermalinkAdd Route

Endpoints

/routes/

PermalinkRequest 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.
regex_priority
optional		 Determines the relative order of this Route against others when evaluating regex paths. Routes with higher numbers will have their regex paths evaluated first. Defaults to 0.
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"
    }
}

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

PermalinkList Routes

Endpoints

/routes

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

PermalinkList Routes associated to a Service

Endpoints

/services/{service name or id}/routes

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

PermalinkUpdate Route

Endpoint

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

PermalinkRequest 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.
regex_priority
optional		 Determines the relative order of this Route against others when evaluating regex paths. Routes with higher numbers will have their regex paths evaluated first. Defaults to 0.
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
}

PermalinkDelete Route

Endpoint

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

Response

HTTP 204 No Content

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

PermalinkAdd API

Endpoint

/apis/

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

PermalinkRetrieve API

Endpoint

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

Response

HTTP 200 OK

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

PermalinkList APIs

Endpoint

/apis/

PermalinkRequest Querystring Parameters

Attributes Description
id
optional		 A filter on the list based on the apis id field.
name
optional		 A filter on the list based on the apis name field.
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"
}

PermalinkUpdate API

Endpoint

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

PermalinkRequest Body

Attribute Description
name 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"
}

PermalinkUpdate Or Create API

Endpoint

/apis/

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

PermalinkDelete API

Endpoint

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

Response

HTTP 204 No Content

PermalinkConsumer Object

The Consumer object represents a consumer - or a user - of 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"
}

PermalinkCreate Consumer

Endpoint

/consumers/

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

PermalinkRetrieve Consumer

Endpoint

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

Response

HTTP 200 OK

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

PermalinkList Consumers

Endpoint

/consumers/

PermalinkRequest Querystring Parameters

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

Response

HTTP 200 OK

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

PermalinkUpdate Consumer

Endpoint

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

PermalinkRequest Body

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

PermalinkUpdate Or Create Consumer

Endpoint

/consumers/

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

PermalinkDelete Consumer

Endpoint

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

Response

HTTP 204 No Content

PermalinkPlugin Object

A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response 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 Kong Hub.

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.

PermalinkPrecedence

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.

PermalinkAdd 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/

PermalinkRequest Body

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

Response

HTTP 201 Created

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

PermalinkRetrieve Plugin

/plugins/{id}

PermalinkRequest Querystring Parameters

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

Response

HTTP 200 OK

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

PermalinkList All Plugins

Endpoint

/plugins/

PermalinkRequest Querystring Parameters

Attributes Description
id
optional		 A filter on the list based on the id field.
name
optional		 A filter on the list based on the name field.
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"
}

PermalinkUpdate Plugin

Endpoint

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

PermalinkRequest Body

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

Response

HTTP 200 OK

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

PermalinkUpdate or Add Plugin

Endpoint

/plugins/

PermalinkRequest Body

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

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

PermalinkDelete Plugin

Endpoint

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

Response

HTTP 204 No Content

PermalinkRetrieve Enabled Plugins

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

Endpoint

/plugins/enabled

Response

HTTP 200 OK

{
    "enabled_plugins": [
        "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"
    ]
}

PermalinkRetrieve Plugin Schema

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

/plugins/schema/{plugin name}

Response

HTTP 200 OK

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

PermalinkCertificate 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-----..."
}

PermalinkAdd Certificate

Endpoint

/certificates/

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

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

PermalinkList 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
        }
    ]
}

PermalinkUpdate Certificate

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

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

PermalinkUpdate or Create Certificate

Endpoint

/certificates/

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

PermalinkDelete 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

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

PermalinkAdd SNI

Endpoint

/snis/

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

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

PermalinkList 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
        }
    ]
}

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

PermalinkUpdate or Create SNI

Endpoint

/snis/

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

PermalinkDelete SNI

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

Response

HTTP 204 No Content

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

PermalinkAdd upstream

Endpoint

/upstreams/

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

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

PermalinkList upstreams

Endpoint

/upstreams/

PermalinkRequest 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=="
}

PermalinkUpdate upstream

Endpoint

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

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

PermalinkUpdate Or create Upstream

Endpoint

/upstreams/

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

PermalinkDelete 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

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

PermalinkEndpoint

/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
        }
    ]
}

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

PermalinkAdd 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

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

PermalinkList 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

PermalinkRequest 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
        }
    ]
}

PermalinkList 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+

PermalinkEndpoint

/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
        }
    ]
}

PermalinkDelete 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

PermalinkSet 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

PermalinkSet 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