You are browsing documentation for an older version. See the latest documentation here.
Plugin Development - Extending the Admin API
Notes:
- This chapter assumes that you have a relative knowledge of Lapis.
- The Admin API extensions are available only for HTTP plugins, not Stream plugins.
Kong can be configured using a REST interface referred to as the Admin API. Plugins can extend it by adding their own endpoints to accommodate custom entities or other personalized management needs. A typical example of this is the creation, retrieval, and deletion (commonly referred to as “CRUD operations”) of API keys.
The Admin API is a Lapis application, and Kong’s level of abstraction makes it easy for you to add endpoints.
Module
kong.plugins.<plugin_name>.api
Add endpoints to the Admin API
Kong will detect and load your endpoints if they are defined in a module named:
"kong.plugins.<plugin_name>.api"
This module is bound to return a table with one or more entries with the following structure:
{
["<path>"] = {
schema = <schema>,
methods = {
before = function(self) ... end,
on_error = function(self) ... end,
GET = function(self) ... end,
PUT = function(self) ... end,
...
}
},
...
}
Where:
-
<path>
should be a string representing a route like/users
(See Lapis routes & URL Patterns) for details. Notice that the path can contain interpolation parameters, like/users/:users/new
. -
<schema>
is a schema definition. Schemas for core and custom plugin entities are available viakong.db.<entity>.schema
. The schema is used to parse certain fields according to their types; for example if a field is marked as an integer, it will be parsed as such when it is passed to a function (by default form fields are all strings). - The
methods
subtable contains functions, indexed by a string.- The
before
key is optional and can hold a function. If present, the function will be executed on every request that hitspath
, before any other function is invoked. - One or more functions can be indexed with HTTP method names, like
GET
orPUT
. These functions will be executed when the appropriate HTTP method andpath
is matched. If abefore
function is present on thepath
, it will be executed first. Keep in mind thatbefore
functions can usekong.response.exit
to finish early, effectively cancelling the “regular” http method function. - The
on_error
key is optional and can hold a function. If present, the function will be executed when the code from other functions (either from abefore
or a “http method”) throws an error. If not present, then Kong will use a default error handler to return the errors.
- The
For example:
local endpoints = require "kong.api.endpoints"
local credentials_schema = kong.db.keyauth_credentials.schema
local consumers_schema = kong.db.consumers.schema
return {
["/consumers/:consumers/key-auth"] = {
schema = credentials_schema,
methods = {
GET = endpoints.get_collection_endpoint(
credentials_schema, consumers_schema, "consumer"),
POST = endpoints.post_collection_endpoint(
credentials_schema, consumers_schema, "consumer"),
},
},
}
This code will create two Admin API endpoints in /consumers/:consumers/key-auth
, to
obtain (GET
) and create (POST
) credentials associated to a given consumer. In this example,
the functions are provided by the kong.api.endpoints
library.
The endpoints
module currently contains the default implementation for the most usual CRUD
operations used in Kong. This module provides you with helpers for any insert, retrieve,
update or delete operations and performs the necessary DAO operations and replies with
the appropriate HTTP status codes. It also provides you with functions to retrieve parameters from
the path, such as an Service’s name or id, or a Consumer’s username or id.
If endpoints
-provided are functions not enough, a regular Lua function can be used instead. From there you can use:
- Several functions provided by the
endpoints
module. - All the functionality provided by the PDK
- The
self
parameter, which is the Lapis request object. - And of course you can
require
any Lua modules if needed. Make sure they are compatible with OpenResty if you choose this route.
local endpoints = require "kong.api.endpoints"
local credentials_schema = kong.db.keyauth_credentials.schema
local consumers_schema = kong.db.consumers.schema
return {
["/consumers/:consumers/key-auth/:keyauth_credentials"] = {
schema = credentials_schema,
methods = {
before = function(self, db, helpers)
local consumer, _, err_t = endpoints.select_entity(self, db, consumers_schema)
if err_t then
return endpoints.handle_error(err_t)
end
if not consumer then
return kong.response.exit(404, { message = "Not found" })
end
self.consumer = consumer
if self.req.method ~= "PUT" then
local cred, _, err_t = endpoints.select_entity(self, db, credentials_schema)
if err_t then
return endpoints.handle_error(err_t)
end
if not cred or cred.consumer.id ~= consumer.id then
return kong.response.exit(404, { message = "Not found" })
end
self.keyauth_credential = cred
self.params.keyauth_credentials = cred.id
end
end,
GET = endpoints.get_entity_endpoint(credentials_schema),
PUT = function(self, db, helpers)
self.args.post.consumer = { id = self.consumer.id }
return endpoints.put_entity_endpoint(credentials_schema)(self, db, helpers)
end,
},
},
}
On the previous example, the /consumers/:consumers/key-auth/:keyauth_credentials
path gets
three functions:
- The
before
function is a custom Lua function which uses severalendpoints
-provided utilities (endpoints.handle_error
) as well as PDK functions (kong.response.exit
). It also populatesself.consumer
for the subsequent functions to use. - The
GET
function is built entirely usingendpoints
. This is possible because thebefore
has “prepared” things in advance, likeself.consumer
. - The
PUT
function populatesself.args.post.consumer
before calling theendpoints
-providedput_entity_endpoint
function.