このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
Kong Gateway 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 Securing the Admin API for more information about security methods.
Documentation
The Kong Admin API is documented in OpenAPI format:
Spec | Insomnia link |
---|---|
Enterprise API | |
Open source API |
See the following links for individual entity documentation:
DB-less mode
In DB-less mode, you configure Kong Gateway declaratively. 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. Therefore, the Admin API is mostly read-only.
When running Kong Gateway in DB-less mode, the Admin API can only perform tasks related to handling the declarative config:
- Validating configurations against schemas
- Validating plugin configurations against schemas
- Reloading the declarative configuration
Supported content types
The Admin API accepts 3 content types on every endpoint:
application/json
The application/json
content type is useful for complex bodies (for example, complex plugin configuration).
Send a JSON representation of the data you want to send. For example:
{
"config": {
"limit": 10,
"period": "seconds"
}
}
Here’s an example of 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
The content type application/x-www-form-urlencoded
is useful for basic request bodies.
You can use it in most situations.
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).
Here’s 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
The multipart/form-data
content type is 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.
For example, here’s a 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"
HTTP status response codes
The following status codes are returned in HTTP responses:
HTTP Code | HTTP Description | Notes | Request method |
---|---|---|---|
200 | OK | The request succeeded. The result of a 200 request depends on the request type: - GET : The resource was fetched and sent in the message body. - PUT or POST : The resource that describes the result of the action is sent in the message body. - PATCH : ? |
GET , POST , PATCH , PUT
|
201 | Created | The request succeeded and a new resource was created. | POST |
204 | No Content | There is no content in the request to send. | DELETE |
400 | Bad Request | The server can’t or won’t send the request because of an error by the client. |
POST , PATCH , PUT
|
401 | Unauthorized | The client is unauthenticated. |
GET , POST , DELETE , PATCH , PUT
|
404 | Not Found | The server can’t find the resource you requested. With an API, this can mean that the endpoint is valid but the resource doesn’t exist. |
GET , PATCH , PUT
|
405 | Method Not Allowed | The server knows the request method, but it isn’t supported by the resource. | PUT |
409 | Conflict | A request conflicts with the current state of the server. | POST |
Using the API in workspaces
Any requests that don’t specify a workspace target the default
workspace.
To target a different workspace, prefix any endpoint with the workspace name or ID:
http://localhost:8001/<WORKSPACE_NAME|ID>/<ENDPOINT>
For example, if you don’t specify a workspace,
this request retrieves a list of services from the default
workspace:
curl -i -X GET http://localhost:8001/services
While this request retrieves all services from the workspace SRE
:
curl -i -X GET http://localhost:8001/SRE/services