Admin API
Kong Admin API
Kong comes with an internal RESTful API for administration purposes. API commands can be run on any node in the cluster, and Kong will keep the configuration consistent across all nodes.
- The RESTful Admin API listens on port
8001
by default.
Supported Content Types
The Admin API accepts 2 content types on every endpoint:
- x-www-form-urlencoded
Simple enough for basic request bodies, you will probably use it most of the time. Note that when sending nested values, Kong expects nested objects to be referenced with dotted keys. Example:
value.limit=10&value.period=seconds
- application/json
Handy for complex bodies (ex: complex plugin configuration), in that case simply send a JSON representaton of the data you want to send. Example:
{
"value": {
"limit": 10,
"period": "seconds"
}
}
API Object
The API object describes an API that’s being exposed by Kong. In order to do that Kong needs to know what is going to be the DNS address that will be pointing to the API, and what is the final target URL of the API where the requests will be proxied. Kong can serve more than one API domain.
{
"name": "Mockbin",
"public_dns": "mockbin.com",
"path": "/someservice",
"strip_path": false,
"target_url": "https://mockbin.com"
}
Add API
Endpoint
Request Body
Attribute | Description |
---|---|
name optional |
The API name. If none is specified, will default to the public_dns . |
public_dns semi-optional |
The public DNS address that points to your API. For example, mockbin.com . At least public_dns or path or both should be specified. |
path semi-optional |
The public path that points to your API. For example, /someservice . At least public_dns or path or both should be specified. |
strip_path optional |
Strip the path value before proxying the request to the final API. For example a request made to /someservice/hello will be resolved to target_url/hello . By default is false . |
target_url |
The base target URL that points to your API server, this URL will be used for proxying requests. For example, https://mockbin.com . |
Response
HTTP 201 Created
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"name": "Mockbin",
"public_dns": "mockbin.com",
"target_url": "http://mockbin.com",
"created_at": 1422386534
}
Retrieve API
Endpoint
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the API to retrieve |
Response
HTTP 200 OK
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"name": "Mockbin",
"public_dns": "mockbin.com",
"target_url": "https://mockbin.com",
"created_at": 1422386534
}
List APIs
Endpoint
Request Querystring Parameters
Attributes | Description |
---|---|
id optional |
A filter on the list based on the apis id field. |
name optional |
A filter on the list based on the apis name field. |
public_dns optional |
A filter on the list based on the apis public_dns field. |
target_url optional |
A filter on the list based on the apis target_url field. |
size optional, default is 100 |
A limit on the number of objects to be returned. |
offset optional |
A cursor used for pagination. offset is an object identifier that defines a place in the list. |
Response
HTTP 200 OK
{
"total": 2,
"data": [
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"name": "Mockbin",
"public_dns": "mockbin.com",
"target_url": "https://mockbin.com",
"created_at": 1422386534
},
{
"id": "3f924084-1adb-40a5-c042-63b19db421a2",
"name": "PrivateAPI",
"public_dns": "internal.api.com",
"target_url": "http://private.api.com",
"created_at": 1422386585
}
],
"next": "http://localhost:8001/apis/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}
Update API
Endpoint
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the API to update |
Request Body
Attribute | Description |
---|---|
name optional |
The API name. If none is specified, will default to the public_dns . |
public_dns semi-optional |
The public DNS address that points to your API. For example, mockbin.com . At least public_dns or path or both should be specified. |
path semi-optional |
The public path that points to your API. For example, /someservice . At least public_dns or path or both should be specified. |
strip_path optional |
Strip the path value before proxying the request to the final API. For example a request made to /someservice/hello will be resolved to target_url/hello . By default is false . |
target_url |
The base target URL that points to your API server, this URL will be used for proxying requests. For example, https://mockbin.com . |
Response
HTTP 200 OK
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"name": "Mockbin2",
"public_dns": "mockbin.com",
"target_url": "http://mockbin.com",
"created_at": 1422386534
}
Update Or Create API
Endpoint
Request Body
Attribute | Description |
---|---|
name optional |
The API name. If none is specified, will default to the public_dns . |
public_dns semi-optional |
The public DNS address that points to your API. For example, mockbin.com . At least public_dns or path or both should be specified. |
path semi-optional |
The public path that points to your API. For example, /someservice . At least public_dns or path or both should be specified. |
strip_path optional |
Strip the path value before proxying the request to the final API. For example a request made to /someservice/hello will be resolved to target_url/hello . By default is false . |
target_url |
The base target URL that points to your API server, this URL will be used for proxying requests. For example, https://mockbin.com . |
The body needs an id
parameter to trigger an update on an existing entity.
Response
HTTP 201 Created or HTTP 200 OK
See POST and PATCH responses.
Delete API
Endpoint
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the API to delete |
Response
HTTP 204 NO CONTENT
Consumer Object
The Consumer object represents a consumer - or a user - of an API. You can either rely on Kong as the primary datastore, or you can be map the consumer list with your database to keep consistency between Kong and your existing primary datastore.
{
"custom_id": "abc123"
}
Create Consumer
Endpoint
Request Form Parameters
Attributes | Description |
---|---|
username semi-optional |
The username of the consumer. You must send either this field or custom_id with the request. |
custom_id semi-optional |
Field for storing an existing ID for the consumer, useful for mapping Kong with users in your existing database. You must send either this field or username with the request. |
Response
HTTP 201 Created
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"custom_id": "abc123",
"created_at": 1422386534
}
Retrieve Consumer
Endpoint
Attributes | Description |
---|---|
username or id required |
The unique identifier or the username of the consumer to retrieve |
Response
HTTP 200 OK
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"custom_id": "abc123",
"created_at": 1422386534
}
List Consumers
Endpoint
Request Querystring Parameters
Attributes | Description |
---|---|
id optional |
A filter on the list based on the consumer id field. |
custom_id optional |
A filter on the list based on the consumer custom_id field. |
username optional |
A filter on the list based on the consumer username field. |
size optional, default is 100 |
A limit on the number of objects to be returned. |
offset optional |
A cursor used for pagination. offset is an object identifier that defines a place in the list. |
Response
HTTP 200 OK
{
"total": 2,
"data": [
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"custom_id": "abc123",
"created_at": 1422386534
},
{
"id": "3f924084-1adb-40a5-c042-63b19db421a2",
"custom_id": "def345",
"created_at": 1422386585
}
],
"next": "http://localhost:8001/consumers/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}
Update Consumer
Endpoint
Attributes | Description |
---|---|
username or id required |
The unique identifier or the username of the consumer to update |
Request Body
Attributes | Description |
---|---|
username semi-optional |
The username of the consumer. You must send either this field or custom_id with the request. |
custom_id semi-optional |
Field for storing an existing ID for the consumer, useful for mapping Kong with users in your existing database. You must send either this field or username with the request. |
Response
HTTP 200 OK
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"custom_id": "updated_abc123",
"created_at": 1422386534
}
Update Or Create Consumer
Endpoint
Request Body
Attributes | Description |
---|---|
username semi-optional |
The username of the consumer. You must send either this field or custom_id with the request. |
custom_id semi-optional |
Field for storing an existing ID for the consumer, useful for mapping Kong with users in your existing database. You must send either this field or username with the request. |
The body needs an id
parameter to trigger an update on an existing entity.
Response
HTTP 201 Created or HTTP 200 OK
See POST and PATCH responses.
Delete Consumer
Endpoint
Attributes | Description |
---|---|
username or id required |
The unique identifier or the name of the consumer to delete |
Response
HTTP 204 NO CONTENT
Plugin Configuration Object
The Plugin Configuration object represents a plugin configuration that will be executed during the HTTP request/response workflow, and it’s how you can add functionalities to APIs that run behind Kong, like Authentication or Rate Limiting for example. You can find more information about how to install and what values each plugin takes by visiting the Kong Hub.
When creating a Plugin Configuration on top of an API, every request made by a client will be evaluated by the plugin configuration you setup. Sometimes the Plugin Configuration needs to be tuned to different values for some specific consumers, you can do that by specifying the consumer_id
value.
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
"name": "ratelimiting",
"value": {
"limit": 20,
"period": "minute"
},
"created_at": 1422386534
}
Create Plugin Configuration
Endpoint
Attributes | Description |
---|---|
name or id required |
The unique identifier or the name of the API on which to add a plugin configuration |
Request Body
Attributes | Description |
---|---|
name |
The name of the Plugin that’s going to be added. Currently the Plugin must be installed in every Kong instance separately. |
consumer_id optional |
The unique identifier of the consumer that overrides the existing settings for this specific consumer on incoming requests. |
value.{property} |
The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub. |
enabled |
Whether the plugin is applied. Default: true . |
Response
HTTP 201 Created
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
"name": "ratelimiting",
"value": {
"limit": 20,
"period": "minute"
},
"created_at": 1422386534
}
List Per-API Plugin Configurations
Endpoint
Request Querystring Parameters
Attributes | Description |
---|---|
id optional |
A filter on the list based on the id field. |
name optional |
A filter on the list based on the name field. |
api_id optional |
A filter on the list based on the api_id field. |
consumer_id optional |
A filter on the list based on the consumer_id field. |
size optional, default is 100 |
A limit on the number of objects to be returned. |
offset optional |
A cursor used for pagination. offset is an object identifier that defines a place in the list. |
Response
HTTP 200 OK
{
"total": 2,
"data": [
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"name": "ratelimiting",
"value": {
"limit": 20,
"period": "minute"
},
"created_at": 1422386534
},
{
"id": "3f924084-1adb-40a5-c042-63b19db421a2",
"api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
"name": "ratelimiting",
"value": {
"limit": 300,
"period": "hour"
},
"created_at": 1422386585
}
],
"next": "http://localhost:8001/plugins_configurations/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}
List All Plugin Configurations
You can use the /plugins_configuration
endpoint to access a global list of all the configured plugins on your cluster.
Endpoint
Request Querystring Parameters
Attributes | Description |
---|---|
id optional |
A filter on the list based on the id field. |
name optional |
A filter on the list based on the name field. |
api_id optional |
A filter on the list based on the api_id field. |
consumer_id optional |
A filter on the list based on the consumer_id field. |
size optional, default is 100 |
A limit on the number of objects to be returned. |
offset optional |
A cursor used for pagination. offset is an object identifier that defines a place in the list. |
Response
HTTP 200 OK
{
"total": 2,
"data": [
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"name": "ratelimiting",
"value": {
"limit": 20,
"period": "minute"
},
"created_at": 1422386534
},
{
"id": "3f924084-1adb-40a5-c042-63b19db421a2",
"api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
"name": "ratelimiting",
"value": {
"limit": 300,
"period": "hour"
},
"created_at": 1422386585
}
],
"next": "http://localhost:8001/plugins_configurations/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}
Update Plugin Configuration
Endpoint
Attributes | Description |
---|---|
api name or id required |
The unique identifier or the name of the API for which to update the plugin configuration |
plugin configuration name or id required |
The unique identifier or the name of the plugin for which to update the configuration on this API |
Request Body
Attributes | Description |
---|---|
name |
The name of the Plugin that’s going to be added. Currently the Plugin must be installed in every Kong instance separately. |
consumer_id optional |
The unique identifier of the consumer that overrides the existing settings for this specific consumer on incoming requests. |
value.{property} |
The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub. |
enabled |
Whether the plugin is applied. Default: true . |
Response
HTTP 200 OK
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
"name": "ratelimiting",
"value": {
"limit": 50,
"period": "second"
},
"created_at": 1422386534
}
Update Or Create Plugin Configuration
Endpoint
Attributes | Description |
---|---|
api name or id required |
The unique identifier or the name of the API for which to update or create the plugin configuration |
Request Body
Attributes | Description |
---|---|
name |
The name of the Plugin that’s going to be added. Currently the Plugin must be installed in every Kong instance separately. |
consumer_id optional |
The unique identifier of the consumer that overrides the existing settings for this specific consumer on incoming requests. |
value.{property} |
The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub. |
enabled |
Whether the plugin is applied. Default: true . |
The body needs an id
parameter to trigger an update on an existing entity.
Response
HTTP 201 Created or HTTP 200 OK
See POST and PATCH responses.
Delete Plugin Configuration
Endpoint
Attributes | Description |
---|---|
api name or id required |
The unique identifier or the name of the API for which to delete the plugin configuration |
plugin configuration name or id required |
The unique identifier or the name of the plugin for which to delete the configuration on this API |
Response
HTTP 204 NO CONTENT