Admin API
Introduction
Kong comes with an internal RESTful API for administration purposes. API commands can be run on any node in the cluster, and Kong will keep the configuration consistent across all nodes.
- The RESTful Admin API listens on port
8001
.
API Object
The API object describes an API that’s being exposed by Kong. In order to do that Kong needs to know what is going to be the DNS address that will be pointing to the API, and what is the final target URL of the API where the requests will be proxied. Kong can serve more than one API domain.
{
"name": "Mockbin",
"public_dns": "mockbin.com",
"target_url": "https://mockbin.com"
}
Add API
Endpoint
Request Form Parameters
Attributes | Description |
---|---|
name optional |
API name. If none is specified, will default to the public_dns . |
public_dns |
The public DNS address that points to your API. For example, mockbin.com . |
target_url |
The base target URL that points to your API server, this URL will be used for proxying requests. For example, https://mockbin.com . |
Response
HTTP 201 Created
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"name": "Mockbin",
"public_dns": "mockbin.com",
"target_url": "http://mockbin.com",
"created_at": 1422386534
}
Retrieve API
Endpoint
Attributes | Description |
---|---|
id required |
The unique identifier of the API to be retrieved |
Response
HTTP 200 OK
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"name": "Mockbin",
"public_dns": "mockbin.com",
"target_url": "https://mockbin.com",
"created_at": 1422386534
}
List APIs
Endpoint
Request Querystring Parameters
Attributes | Description |
---|---|
id optional |
A filter on the list based on the apis id field. |
name optional |
A filter on the list based on the apis name field. |
public_dns optional |
A filter on the list based on the apis public_dns field. |
target_url optional |
A filter on the list based on the apis target_url field. |
size optional, default is 10 |
A limit on the number of objects to be returned. |
offset optional |
A cursor used for pagination. offset is an object identifier that defines a place in the list. |
Response
HTTP 200 OK
{
"total": 2,
"data": [
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"name": "Mockbin",
"public_dns": "mockbin.com",
"target_url": "https://mockbin.com",
"created_at": 1422386534
},
{
"id": "3f924084-1adb-40a5-c042-63b19db421a2",
"name": "PrivateAPI",
"public_dns": "internal.api.com",
"target_url": "http://private.api.com",
"created_at": 1422386585
}
],
"next": "http://localhost:8001/apis/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}
Update API
Endpoint
Attributes | Description |
---|---|
id required |
The unique identifier of the API to be updated |
Request Body
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"name": "Mockbin2",
"public_dns": "mockbin.com",
"target_url": "http://mockbin.com",
"created_at": 1422386534
}
Response
HTTP 200 OK
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"name": "Mockbin2",
"public_dns": "mockbin.com",
"target_url": "http://mockbin.com",
"created_at": 1422386534
}
Delete API
Endpoint
Attributes | Description |
---|---|
id required |
The unique identifier of the API to be deleted |
Response
HTTP 204 NO CONTENT
Consumer Object
The Consumer object represents a consumer, or a user, of an API. You can either rely on Kong as the primary datastore, or you can be map the consumer list with your database to keep consistency between Kong and your existing primary datastore.
{
"custom_id": "abc123"
}
Create Consumer
Endpoint
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 |
---|---|
id required |
The unique identifier of the consumer to be retrieved |
Response
HTTP 200 OK
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"custom_id": "abc123",
"created_at": 1422386534
}
List Consumers
Endpoint
Request Querystring Parameters
Attributes | Description |
---|---|
id optional |
A filter on the list based on the consumer id field. |
custom_id optional |
A filter on the list based on the consumer custom_id field. |
username optional |
A filter on the list based on the consumer username field. |
size optional, default is 10 |
A limit on the number of objects to be returned. |
offset optional |
A cursor used for pagination. offset is an object identifier that defines a place in the list. |
Response
HTTP 200 OK
{
"total": 2,
"data": [
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"custom_id": "abc123",
"created_at": 1422386534
},
{
"id": "3f924084-1adb-40a5-c042-63b19db421a2",
"custom_id": "def345",
"created_at": 1422386585
}
],
"next": "http://localhost:8001/consumers/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}
Update Consumer
Endpoint
Attributes | Description |
---|---|
id required |
The unique identifier of the consumer to be updated |
Request Body
{
"custom_id": "updated_abc123"
}
Response
HTTP 200 OK
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"custom_id": "updated_abc123",
"created_at": 1422386534
}
Delete Consumer
Endpoint
Attributes | Description |
---|---|
id required |
The unique identifier of the consumer to be deleted |
Response
HTTP 204 NO CONTENT
Plugin Configuration Object
The Plugin Configuration object represents a plugin configuration that will be executed during the HTTP request/response workflow, and it’s how you can add functionalities to APIs that run behind Kong, like Authentication or Rate Limiting for example. You can find more information about how to install and what values each plugin takes by visiting the 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
Request Form Parameters
Attributes | Description |
---|---|
name |
The name of the Plugin that’s going to be added. Currently the Plugin must be installed in every Kong instance separately. |
api_id |
The unique identifier of the API the plugin will be enabled for. |
consumer_id optional |
The unique identifier of the consumer that overrides the existing settings for this specific consumer on incoming requests. |
value.{property} |
The configuration properties for the Plugin which can be found on the plugins documentation page in the Kong Hub. |
Response
HTTP 201 Created
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
"name": "ratelimiting",
"value": {
"limit": 20,
"period": "minute"
},
"created_at": 1422386534
}
Retrieve Plugin Configuration
Endpoint
Attributes | Description |
---|---|
id required |
The unique identifier of the plugin configuration to be retrieved |
Response
HTTP 200 OK
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
"name": "ratelimiting",
"value": {
"limit": 20,
"period": "minute"
},
"created_at": 1422386534
}
List Plugin Configurations
Endpoint
Request Querystring Parameters
Attributes | Description |
---|---|
id optional |
A filter on the list based on the id field. |
name optional |
A filter on the list based on the name field. |
api_id optional |
A filter on the list based on the api_id field. |
consumer_id optional |
A filter on the list based on the consumer_id field. |
size optional, default is 10 |
A limit on the number of objects to be returned. |
offset optional |
A cursor used for pagination. offset is an object identifier that defines a place in the list. |
Response
HTTP 200 OK
{
"total": 2,
"data": [
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"name": "ratelimiting",
"value": {
"limit": 20,
"period": "minute"
},
"created_at": 1422386534
},
{
"id": "3f924084-1adb-40a5-c042-63b19db421a2",
"api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
"name": "ratelimiting",
"value": {
"limit": 300,
"period": "hour"
},
"created_at": 1422386585
}
],
"next": "http://localhost:8001/plugins_configurations/?size=10&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}
Update Plugin Configuration
Endpoint
Attributes | Description |
---|---|
id required |
The unique identifier of the plugin configuration to be retrieved |
Request Body
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
"name": "ratelimiting",
"value": {
"limit": 50,
"period": "second"
},
"created_at": 1422386534
}
Response
HTTP 200 OK
{
"id": "4d924084-1adb-40a5-c042-63b19db421d1",
"api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
"consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
"name": "ratelimiting",
"value": {
"limit": 50,
"period": "second"
},
"created_at": 1422386534
}
Delete Plugin Configuration
Endpoint
Attributes | Description |
---|---|
id required |
The unique identifier of the plugin configuration to be deleted |
Response
HTTP 204 NO CONTENT