Admin API

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

DB-less Mode

In DB-less mode, the Admin API can be used to load a new declarative configuration, and for inspecting the current configuration. In DB-less mode, the Admin API for each Kong node functions independently, reflecting the memory state of that particular Kong node. This is the case because there is no database coordination between Kong nodes.

In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:

• Validating configurations against schemas
• Validating plugin configurations against schemas
• Reloading the declarative configuration
• Setting a target’s health status in the load balancer

Declarative Configuration

Loading the declarative configuration of entities into Kong Gateway can be done in two ways: at start-up, through the declarative_config property, or at run-time, through the Admin API using the /config endpoint.

To get started using declarative configuration, you need a file (in YAML or JSON format) containing entity definitions. You can generate a sample declarative configuration with the command:

kong config init

It generates a file named kong.yml in the current directory, containing the appropriate structure and examples.

Reload Declarative Configuration

This endpoint allows resetting a DB-less Kong with a new declarative configuration data file. All previous contents are erased from memory, and the entities specified in the given file take their place.

To learn more about the file format, see the declarative configuration documentation.

/config

Request Querystring Parameters

Response

HTTP 200 OK

{
    {
        "services": [],
        "routes": []
    }
}

The response contains a list of all the entities that were parsed from the input file.

Supported Content Types

The Admin API accepts 3 content types on every endpoint:

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

An example adding a Route to a Service named test-service:

curl -i -X POST http://localhost:8001/services/test-service/routes \
     -H "Content-Type: application/json" \
     -d '{"name": "test-route", "paths": [ "/path/one", "/path/two" ]}'

• 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

When specifying arrays, send the values in order, or use square brackets (numbering inside the brackets is optional but if provided it must be 1-indexed, and consecutive). An example Route added to a Service named test-service:

curl -i -X POST http://localhost:8001/services/test-service/routes \
     -d "name=test-route" \
     -d "paths[1]=/path/one" \
     -d "paths[2]=/path/two"

The following two examples are identical to the one above, but less explicit:

curl -i -X POST http://localhost:8001/services/test-service/routes \
     -d "name=test-route" \
     -d "paths[]=/path/one" \
     -d "paths[]=/path/two"
curl -i -X POST http://localhost:8001/services/test-service/routes \
    -d "name=test-route" \
    -d "paths=/path/one" \
    -d "paths=/path/two"

• multipart/form-data

Similar to URL-encoded, this content type uses dotted keys to reference nested objects. Here is an example of sending a Lua file to the pre-function Kong plugin:

curl -i -X POST http://localhost:8001/services/plugin-testing/plugins \
     -F "name=pre-function" \
     -F "config.access=@custom-auth.lua"

When specifying arrays for this content-type, the array indices must be specified. An example Route added to a Service named test-service:

curl -i -X POST http://localhost:8001/services/test-service/routes \
     -F "name=test-route" \
     -F "paths[1]=/path/one" \
     -F "paths[2]=/path/two"

Information Routes

Retrieve Node Information

Retrieve generic details about a node.

/

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.14.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 data store shared by all Kong nodes.

Check Endpoint Or Entity Existence

Similar to HTTP GET, but does not return the body. Returns HTTP 200 when the endpoint exits or HTTP 404 when it does not. Other status codes are possible.

/<any-endpoint>

Response

HTTP 200 OK

Access-Control-Allow-Origin: *
Content-Length: 11389
Content-Type: application/json; charset=utf-8
X-Kong-Admin-Latency: 1

List Http Methods by Endpoint

List all the supported HTTP methods by an endpoint. This can also be used with a CORS preflight request.

/<any-endpoint>

Response

HTTP 204 No Content

Access-Control-Allow-Headers: Content-Type
Access-Control-Allow-Methods: GET, HEAD, OPTIONS
Access-Control-Allow-Origin: *
Allow: GET, HEAD, OPTIONS

List Available Endpoints

List all available endpoints provided by the Admin API.

/endpoints

Response

HTTP 200 OK

{
    "data": [
        "/",
        "/acls",
        "/acls/{acls}",
        "/acls/{acls}/consumer",
        "/basic-auths",
        "/basic-auths/{basicauth_credentials}",
        "/basic-auths/{basicauth_credentials}/consumer",
        "/ca_certificates",
        "/ca_certificates/{ca_certificates}",
        "/cache",
        "/cache/{key}",
        "..."
    ]
}

Validate A Configuration against A Schema

Check validity of a configuration against its entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API.

Note that this only performs the schema validation checks, checking that the input configuration is well-formed. A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store.

/schemas/{entity}/validate

Response

HTTP 200 OK

{
    "message": "schema validation successful"
}

Retrieve Entity Schema

Retrieve the schema of an entity. This is useful to understand what fields an entity accepts, and can be used for building third-party integrations to the Kong.

/schemas/{entity name}

Response

HTTP 200 OK

{
    "fields": [
        {
            "id": {
                "auto": true,
                "type": "string",
                "uuid": true
            }
        },
        {
            "created_at": {
                "auto": true,
                "timestamp": true,
                "type": "integer"
            }
        },
        ...
    ]
}

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.

/schemas/plugins/{plugin name}

Response

HTTP 200 OK

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

Validate A Plugin Configuration against The Schema

Check validity of a plugin configuration against the plugins entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API.

Note that this only performs the schema validation checks, checking that the input configuration is well-formed. A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store.

/schemas/plugins/validate

Response

HTTP 200 OK

{
    "message": "schema validation successful"
}

Retrieve Runtime Debugging Info of Kong’s Timers

Retrieve runtime stats data from lua-resty-timer-ng.

/timers

Response

HTTP 200 OK

{   "worker": {
      "id": 0,
      "count": 4,
    },
    "stats": {
      "flamegraph": {
        "running": "@./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0\n",
        "elapsed_time": "@./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 17\n",
        "pending": "@./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0\n"
      },
      "sys": {
          "running": 0,
          "runs": 7,
          "pending": 0,
          "waiting": 7,
          "total": 7
      },
      "timers": {
          "healthcheck-localhost:8080": {
              "name": "healthcheck-localhost:8080",
              "meta": {
                  "name": "@/build/luarocks/share/lua/5.1/resty/counter.lua:71:new()",
                  "callstack": "@./kong/plugins/prometheus/prometheus.lua:673:init_worker();@/build/luarocks/share/lua/5.1/resty/counter.lua:71:new()"
              },
              "stats": {
                  "finish": 2,
                  "runs": 2,
                  "elapsed_time": {
                      "min": 0,
                      "max": 0,
                      "avg": 0,
                      "variance": 0
                  },
                  "last_err_msg": ""
              }
          }
      }
    }
}

• worker:
  • id: The ordinal number of the current Nginx worker processes (starting from number 0).
  • count: The total number of the Nginx worker processes.
• stats.flamegraph: String-encoded timer-related flamegraph data. You can use brendangregg/FlameGraph to generate flamegraph SVGs.
• stats.sys: List the number of different type of timers.
  • running: number of running timers.
  • pending: number of pending timers.
  • waiting: number of unexpired timers.
  • total: running + pending + waiting.
• timers.meta: Program call stack of created timers.
  • name: An automatically generated string that stores the location where the creation timer was created.
  • callstack: Lua call stack string showing where this timer was created.
• timers.stats.elapsed_time: An object that stores the maximum, minimum, average and variance of the time spent on each run of the timer (second).
• timers.stats.runs: Total number of runs.
• timers.stats.finish: Total number of successful runs.

Note: flamegraph, timers.meta and timers.stats.elapsed_time keys are only available when Kong’s log_level config is set to debug. Read the doc of lua-resty-timer-ng for more details.

Health Routes

Retrieve Node Status

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

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.

/status

Response

HTTP 200 OK

{
    "database": {
      "reachable": true
    },
    "memory": {
        "workers_lua_vms": [{
            "http_allocated_gc": "0.02 MiB",
            "pid": 18477
          }, {
            "http_allocated_gc": "0.02 MiB",
            "pid": 18478
        }],
        "lua_shared_dicts": {
            "kong": {
                "allocated_slabs": "0.04 MiB",
                "capacity": "5.00 MiB"
            },
            "kong_db_cache": {
                "allocated_slabs": "0.80 MiB",
                "capacity": "128.00 MiB"
            },
        }
    },
    "server": {
        "total_requests": 3,
        "connections_active": 1,
        "connections_accepted": 1,
        "connections_handled": 1,
        "connections_reading": 0,
        "connections_writing": 1,
        "connections_waiting": 0
      },
  "configuration_hash": "779742c3d7afee2e38f977044d2ed96b"
}

• memory: Metrics about the memory usage.
  • workers_lua_vms: An array with all workers of the Kong node, where each entry contains:
  • http_allocated_gc: HTTP submodule’s Lua virtual machine’s memory usage information, as reported by collectgarbage("count"), for every active worker, i.e. a worker that received a proxy call in the last 10 seconds.
  • pid: worker’s process identification number.
  • lua_shared_dicts: An array of information about dictionaries that are shared with all workers in a Kong node, where each array node contains how much memory is dedicated for the specific shared dictionary (capacity) and how much of said memory is in use (allocated_slabs). These shared dictionaries have least recent used (LRU) eviction capabilities, so a full dictionary, where allocated_slabs == capacity, will work properly. However for some dictionaries, e.g. cache HIT/MISS shared dictionaries, increasing their size can be beneficial for the overall performance of a Kong node.
  • The memory usage unit and precision can be changed using the querystring arguments unit and scale:
    • unit: one of b/B, k/K, m/M, g/G, which will return results in bytes, kibibytes, mebibytes, or gibibytes, respectively. When “bytes” are requested, the memory values in the response will have a number type instead of string. Defaults to m.
    • scale: the number of digits to the right of the decimal points when values are given in human-readable memory strings (unit other than “bytes”). Defaults to 2. You can get the shared dictionaries memory usage in kibibytes with 4 digits of precision by doing: GET /status?unit=k&scale=4
• 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.
• configuration_hash: The hash of the current configuration. This field is only returned when the Kong node is running in DB-less or data-plane mode. The special return value “00000000000000000000000000000000” means Kong does not currently have a valid configuration loaded.

Tags

Tags are strings associated to entities in Kong.

Tags can contain almost all UTF-8 characters, with the following exceptions:

• , and / are reserved for filtering tags with “and” and “or”, so they are not allowed in tags.
• Non-printable ASCII (for example, the space character) is not allowed.

Most core entities can be tagged via their tags attribute, upon creation or edition.

Tags can be used to filter core entities as well, via the ?tags querystring parameter.

For example: if you normally get a list of all the Services by doing:

GET /services

You can get the list of all the Services tagged example by doing:

GET /services?tags=example

Similarly, if you want to filter Services so that you only get the ones tagged example and admin, you can do that like so:

GET /services?tags=example,admin

Finally, if you wanted to filter the Services tagged example or admin, you could use:

GET /services?tags=example/admin

Some notes:

• A maximum of 5 tags can be queried simultaneously in a single request with , or /
• Mixing operators is not supported: if you try to mix , with / in the same querystring, you will receive an error.
• You may need to quote and/or escape some characters when using them from the command line.
• Filtering by tags is not supported in foreign key relationship endpoints. For example, the tags parameter will be ignored in a request such as GET /services/foo/routes?tags=a,b
• offset parameters are not guaranteed to work if the tags parameter is altered or removed

List All Tags

Returns a paginated list of all the tags in the system.

The list of entities will not be restricted to a single entity type: all the entities tagged with tags will be present on this list.

If an entity is tagged with more than one tag, the entity_id for that entity will appear more than once in the resulting list. Similarly, if several entities have been tagged with the same tag, the tag will appear in several items of this list.

/tags

Response

HTTP 200 OK

{
    {
      "data": [
        { "entity_name": "services",
          "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4",
          "tag": "s1",
        },
        { "entity_name": "services",
          "entity_id": "acf60b10-125c-4c1a-bffe-6ed55daefba4",
          "tag": "s2",
        },
        { "entity_name": "routes",
          "entity_id": "60631e85-ba6d-4c59-bd28-e36dd90f6000",
          "tag": "s1",
        },
        ...
      ],
      "offset": "c47139f3-d780-483d-8a97-17e9adc5a7ab",
      "next": "/tags?offset=c47139f3-d780-483d-8a97-17e9adc5a7ab",
    }
}

List Entity Ids by Tag

Returns the entities that have been tagged with the specified tag.

The list of entities will not be restricted to a single entity type: all the entities tagged with tags will be present on this list.

/tags/{tags}

Response

HTTP 200 OK

{
    {
      "data": [
        { "entity_name": "services",
          "entity_id": "c87440e1-0496-420b-b06f-dac59544bb6c",
          "tag": "example",
        },
        { "entity_name": "routes",
          "entity_id": "8a99e4b1-d268-446b-ab8b-cd25cff129b1",
          "tag": "example",
        },
        ...
      ],
      "offset": "1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9",
      "next": "/tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9",
    }
}

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.

Services can be both tagged and filtered by tags.

{
    "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/some_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["user-level", "low-priority"],
    "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
    "tls_verify": true,
    "tls_verify_depth": null,
    "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
    "enabled": true
}

Add Service

Note: This API is not available in DB-less mode.

Create Service

/services

Create Service Associated to a Specific Certificate

/certificates/{certificate name or id}/services

Request Body

Response

HTTP 201 Created

{
    "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/some_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["user-level", "low-priority"],
    "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
    "tls_verify": true,
    "tls_verify_depth": null,
    "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
    "enabled": true
}

List Services

List All Services

/services

List Services Associated to a Specific Certificate

/certificates/{certificate name or id}/services

Response

HTTP 200 OK

{
"data": [{
    "id": "a5fb8d9b-a99d-40e9-9d35-72d42a62d83a",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/some_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["user-level", "low-priority"],
    "client_certificate": {"id":"51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"},
    "tls_verify": true,
    "tls_verify_depth": null,
    "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
    "enabled": true
}, {
    "id": "fc73f2af-890d-4f9b-8363-af8945001f7f",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/another_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["admin", "high-priority", "critical"],
    "client_certificate": {"id":"4506673d-c825-444c-a25b-602e3c2ec16e"},
    "tls_verify": true,
    "tls_verify_depth": null,
    "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
    "enabled": true
}],
    "next": "http://localhost:8001/services?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

Retrieve Service

Retrieve Service

/services/{service name or id}

Retrieve Service Associated to a Specific Certificate

/certificates/{certificate id}/services/{service name or id}

Retrieve Service Associated to a Specific Route

/routes/{route name or id}/service

Retrieve Service Associated to a Specific Plugin

/plugins/{plugin id}/service

Response

HTTP 200 OK

{
    "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/some_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["user-level", "low-priority"],
    "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
    "tls_verify": true,
    "tls_verify_depth": null,
    "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
    "enabled": true
}

Update Service

Note: This API is not available in DB-less mode.

Update Service

/services/{service name or id}

Update Service Associated to a Specific Certificate

/certificates/{certificate id}/services/{service name or id}

Update Service Associated to a Specific Route

/routes/{route name or id}/service

Update Service Associated to a Specific Plugin

/plugins/{plugin id}/service

Request Body

Response

HTTP 200 OK

{
    "id": "9748f662-7711-4a90-8186-dc02f10eb0f5",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-service",
    "retries": 5,
    "protocol": "http",
    "host": "example.com",
    "port": 80,
    "path": "/some_api",
    "connect_timeout": 60000,
    "write_timeout": 60000,
    "read_timeout": 60000,
    "tags": ["user-level", "low-priority"],
    "client_certificate": {"id":"4e3ad2e4-0bc4-4638-8e34-c84a417ba39b"},
    "tls_verify": true,
    "tls_verify_depth": null,
    "ca_certificates": ["4e3ad2e4-0bc4-4638-8e34-c84a417ba39b", "51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515"],
    "enabled": true
}

Update Or Create Service

Note: This API is not available in DB-less mode.

Create Or Update Service

/services/{service name or id}

Create Or Update Service Associated to a Specific Certificate

/certificates/{certificate id}/services/{service name or id}

Create Or Update Service Associated to a Specific Route

/routes/{route name or id}/service

Create Or Update Service Associated to a Specific Plugin

/plugins/{plugin id}/service

Request Body

Inserts (or replaces) the Service under the requested resource with the definition specified in the body. The Service will be identified via the name or id attribute.

When the name or id attribute has the structure of a UUID, the Service being inserted/replaced will be identified by its id. Otherwise it will be identified by its name.

When creating a new Service without specifying id (neither in the URL nor in the body), then it will be auto-generated.

Notice that specifying a name in the URL and a different one in the request body is not allowed.

Response

HTTP 200 OK

See POST and PATCH responses.

Delete Service

Note: This API is not available in DB-less mode.

Delete Service

/services/{service name or id}

Delete Service Associated to a Specific Certificate

/certificates/{certificate id}/services/{service name or id}

Response

HTTP 204 No Content

Route Object

Route entities define 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.

You need at least one matching rule that applies to the protocol being matched by the Route. Depending on the protocols configured to be matched by the Route (as defined with the protocols field), this means that at least one of the following attributes must be set:

• For http, at least one of methods, hosts, headers or paths;
• For https, at least one of methods, hosts, headers, paths or snis;
• For tcp, at least one of sources or destinations;
• For tls, at least one of sources, destinations or snis;
• For tls_passthrough, set snis;
• For grpc, at least one of hosts, headers or paths;
• For grpcs, at least one of hosts, headers, paths or snis.
• For ws, at least one of hosts, headers or paths;
• For wss, at least one of hosts, headers, paths or snis;

A route can’t have both tls and tls_passthrough protocols at same time.

The 3.0.x release introduces a new router implementation: atc-router. The router adds:

• Reduced router rebuild time when changing Kong Gateway’s configuration
• Increased runtime performance when routing requests
• Reduced P99 latency from 1.5s to 0.1s with 10,000 routes

Learn more about the router:

• Configure routes using expressions
• Router Expressions language reference

Path handling algorithms

Note: Path handling algorithms v1 was deprecated in Kong 3.0. From Kong 3.0, when router_flavor is set to expressions, route.path_handling will be not be configurable and the path handling behavior will be "v0"; when router_flavor is set to traditional_compatible, the path handling behavior will be "v0" regardless of the value of route.path_handling. Only router_flavor = traditional will support path_handling "v1' behavior.

"v0" is the behavior used in Kong 0.x, 2.x and 3.x. It treats service.path, route.path and request path as segments of a URL. It will always join them via slashes. Given a service path /s, route path /r and request path /re, the concatenated path will be /s/re. If the resulting path is a single slash, no further transformation is done to it. If it’s longer, then the trailing slash is removed.

"v1" is the behavior used in Kong 1.x. It treats service.path as a prefix, and ignores the initial slashes of the request and route paths. Given service path /s, route path /r and request path /re, the concatenated path will be /sre.

Both versions of the algorithm detect “double slashes” when combining paths, replacing them by single slashes.

The following table shows the possible combinations of path handling version, strip path, and request:

Routes can be both tagged and filtered by tags.

{
    "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "path_handling": "v0",
    "preserve_host": false,
    "request_buffering": true,
    "response_buffering": true,
    "tags": ["user-level", "low-priority"],
    "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}

Add Route

Note: This API is not available in DB-less mode.

Create Route

/routes

Create Route Associated to a Specific Service

/services/{service name or id}/routes

Request Body

Response

HTTP 201 Created

{
    "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "path_handling": "v0",
    "preserve_host": false,
    "request_buffering": true,
    "response_buffering": true,
    "tags": ["user-level", "low-priority"],
    "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}

List Routes

List All Routes

/routes

List Routes Associated to a Specific Service

/services/{service name or id}/routes

Response

HTTP 200 OK

{
"data": [{
    "id": "a9daa3ba-8186-4a0d-96e8-00d80ce7240b",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "path_handling": "v0",
    "preserve_host": false,
    "request_buffering": true,
    "response_buffering": true,
    "tags": ["user-level", "low-priority"],
    "service": {"id":"127dfc88-ed57-45bf-b77a-a9d3a152ad31"}
}, {
    "id": "9aa116fd-ef4a-4efa-89bf-a0b17c4be982",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["tcp", "tls"],
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "path_handling": "v0",
    "preserve_host": false,
    "request_buffering": true,
    "response_buffering": true,
    "snis": ["foo.test", "example.com"],
    "sources": [{"ip":"10.1.0.0/16", "port":1234}, {"ip":"10.2.2.2"}, {"port":9123}],
    "destinations": [{"ip":"10.1.0.0/16", "port":1234}, {"ip":"10.2.2.2"}, {"port":9123}],
    "tags": ["admin", "high-priority", "critical"],
    "service": {"id":"ba641b07-e74a-430a-ab46-94b61e5ea66b"}
}],
    "next": "http://localhost:8001/routes?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

Retrieve Route

Retrieve Route

/routes/{route name or id}

Retrieve Route Associated to a Specific Service

/services/{service name or id}/routes/{route name or id}

Retrieve Route Associated to a Specific Plugin

/plugins/{plugin id}/route

Response

HTTP 200 OK

{
    "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "path_handling": "v0",
    "preserve_host": false,
    "request_buffering": true,
    "response_buffering": true,
    "tags": ["user-level", "low-priority"],
    "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}

Update Route

Note: This API is not available in DB-less mode.

Update Route

/routes/{route name or id}

Update Route Associated to a Specific Service

/services/{service name or id}/routes/{route name or id}

Update Route Associated to a Specific Plugin

/plugins/{plugin id}/route

Request Body

Response

HTTP 200 OK

{
    "id": "d35165e2-d03e-461a-bdeb-dad0a112abfe",
    "created_at": 1422386534,
    "updated_at": 1422386534,
    "name": "my-route",
    "protocols": ["http", "https"],
    "methods": ["GET", "POST"],
    "hosts": ["example.com", "foo.test"],
    "paths": ["/foo", "/bar"],
    "headers": {"x-my-header":["foo", "bar"], "x-another-header":["bla"]},
    "https_redirect_status_code": 426,
    "regex_priority": 0,
    "strip_path": true,
    "path_handling": "v0",
    "preserve_host": false,
    "request_buffering": true,
    "response_buffering": true,
    "tags": ["user-level", "low-priority"],
    "service": {"id":"af8330d3-dbdc-48bd-b1be-55b98608834b"}
}

Update Or Create Route

Note: This API is not available in DB-less mode.

Create Or Update Route

/routes/{route name or id}

Create Or Update Route Associated to a Specific Service

/services/{service name or id}/routes/{route name or id}

Create Or Update Route Associated to a Specific Plugin

/plugins/{plugin id}/route

Request Body

Inserts (or replaces) the Route under the requested resource with the definition specified in the body. The Route will be identified via the name or id attribute.

When the name or id attribute has the structure of a UUID, the Route being inserted/replaced will be identified by its id. Otherwise it will be identified by its name.

When creating a new Route without specifying id (neither in the URL nor in the body), then it will be auto-generated.

Notice that specifying a name in the URL and a different one in the request body is not allowed.

Response

HTTP 200 OK

See POST and PATCH responses.

Delete Route

Note: This API is not available in DB-less mode.

Delete Route

/routes/{route name or id}

Delete Route Associated to a Specific Service

/services/{service name or id}/routes/{route name or id}

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 data store, or you can map the consumer list with your database to keep consistency between Kong and your existing primary data store.

Consumers can be both tagged and filtered by tags.

{
    "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
    "created_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["user-level", "low-priority"]
}

Add Consumer

Note: This API is not available in DB-less mode.

Create Consumer

/consumers

Request Body

Response

HTTP 201 Created

{
    "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
    "created_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["user-level", "low-priority"]
}

List Consumers

List All Consumers

/consumers

Response

HTTP 200 OK

{
"data": [{
    "id": "a4407883-c166-43fd-80ca-3ca035b0cdb7",
    "created_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["user-level", "low-priority"]
}, {
    "id": "01c23299-839c-49a5-a6d5-8864c09184af",
    "created_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["admin", "high-priority", "critical"]
}],
    "next": "http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

Retrieve Consumer

Retrieve Consumer

/consumers/{consumer username or id}

Retrieve Consumer Associated to a Specific Plugin

/plugins/{plugin id}/consumer

Response

HTTP 200 OK

{
    "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
    "created_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["user-level", "low-priority"]
}

Update Consumer

Note: This API is not available in DB-less mode.

Update Consumer

/consumers/{consumer username or id}

Update Consumer Associated to a Specific Plugin

/plugins/{plugin id}/consumer

Request Body

Response

HTTP 200 OK

{
    "id": "ec1a1f6f-2aa4-4e58-93ff-b56368f19b27",
    "created_at": 1422386534,
    "username": "my-username",
    "custom_id": "my-custom-id",
    "tags": ["user-level", "low-priority"]
}

Update Or Create Consumer

Note: This API is not available in DB-less mode.

Create Or Update Consumer

/consumers/{consumer username or id}

Create Or Update Consumer Associated to a Specific Plugin

/plugins/{plugin id}/consumer

Request Body

Inserts (or replaces) the Consumer under the requested resource with the definition specified in the body. The Consumer will be identified via the username or id attribute.

When the username or id attribute has the structure of a UUID, the Consumer being inserted/replaced will be identified by its id. Otherwise it will be identified by its username.

When creating a new Consumer without specifying id (neither in the URL nor in the body), then it will be auto-generated.

Notice that specifying a username in the URL and a different one in the request body is not allowed.

Response

HTTP 200 OK

See POST and PATCH responses.

Delete Consumer

Note: This API is not available in DB-less mode.

Delete Consumer

/consumers/{consumer username or id}

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 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 creating a separate plugin instance that specifies both the Service and the Consumer, through the service and consumer fields.

Plugins can be both tagged and filtered by tags.

{
    "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "config": {"minute":20, "hour":500},
    "protocols": ["http", "https"],
    "enabled": true,
    "tags": ["user-level", "low-priority"],
    "ordering": {"before":["plugin-name"]}
}

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

Note: This API is not available in DB-less mode.

Create Plugin

/plugins

Create Plugin Associated to a Specific Route

/routes/{route name or id}/plugins

Create Plugin Associated to a Specific Service

/services/{service name or id}/plugins

Create Plugin Associated to a Specific Consumer

/consumers/{consumer name or id}/plugins

Request Body

Response

HTTP 201 Created

{
    "id": "ce44eef5-41ed-47f6-baab-f725cecf98c7",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "config": {"minute":20, "hour":500},
    "protocols": ["http", "https"],
    "enabled": true,
    "tags": ["user-level", "low-priority"],
    "ordering": {"before":["plugin-name"]}
}

List Plugins

List All Plugins

/plugins

List Plugins Associated to a Specific Route

/routes/{route name or id}/plugins

List Plugins Associated to a Specific Service

/services/{service name or id}/plugins

List Plugins Associated to a Specific Consumer

/consumers/{consumer name or id}/plugins

Response

HTTP 200 OK

{
"data": [{
    "id": "02621eee-8309-4bf6-b36b-a82017a5393e",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "config": {"minute":20, "hour":500},
    "protocols": ["http", "https"],
    "enabled": true,
    "tags": ["user-level", "low-priority"],
    "ordering": {"before":["plugin-name"]}
}, {
    "id": "66c7b5c4-4aaf-4119-af1e-ee3ad75d0af4",
    "name": "rate-limiting",
    "created_at": 1422386534,
    "route": null,
    "service": null,
    "consumer": null,
    "config": {"minute":20, "hour":500},
    "protocols": ["tcp", "tls"],
    "enabled": true,
    "tags": ["admin", "high-priority", "critical"],
    "ordering": {"after":["plugin-name"]}
}],
    "next": "http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}