PermalinkPlugin Development - Extending the Admin API

PermalinkIntroduction

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.

PermalinkModule

kong.plugins.<plugin_name>.api

Back to TOC

PermalinkAdding 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 containing strings describing your routes (See Lapis routes & URL Patterns) and HTTP verbs they support. Routes are then assigned a simple handler function.

This table is then fed to Lapis (See Lapis’ handling HTTP verbs documentation). Example:

return {
  ["/my-plugin/new/get/endpoint"] = {
    GET = function(self, dao_factory, helpers)
      -- ...
    end
  }
}

The handler function takes three arguments, which are, in order:

• self: The request object. See Lapis request object
• dao_factory: The DAO Factory. See the datastore chapter of this guide.
• helpers: A table containing a few helpers, described below.

In addition to the HTTPS verbs it supports, a route table can also contain two other keys:

• before: as in Lapis, a before_filter that runs before the executed verb action.
• on_error: a custom error handler function that overrides the one provided by Kong. See Lapis’ capturing recoverable errors documentation.

Back to TOC

PermalinkHelpers

When handling a request on the Admin API, there are times when you want to send back responses and handle errors, to help you do so the third parameter helpers is a table with the following properties:

• responses: a module with helper functions to send HTTP responses.
• yield_error: the yield_error function from Lapis. To call when your handler encounters an error (from a DAO, for example). Since all Kong errors are tables with context, it can send the appropriate response code depending on the error (Internal Server Error, Bad Request, etc…).

Permalinkcrud_helpers

Since most of the operations you will perform in your endpoints will be CRUD operations, you can also use the kong.api.crud_helpers module. 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 API’s name or id, or a Consumer’s username or id.

Example:

local crud = require "kong.api.crud_helpers"

return {
  ["/consumers/:username_or_id/key-auth/"] = {
    before = function(self, dao_factory, helpers)
      crud.find_consumer_by_username_or_id(self, dao_factory, helpers)
      self.params.consumer_id = self.consumer.id
    end,

    GET = function(self, dao_factory, helpers)
      crud.paginated_set(self, dao_factory.keyauth_credentials)
    end,

    PUT = function(self, dao_factory)
      crud.put(self.params, dao_factory.keyauth_credentials)
    end,

    POST = function(self, dao_factory)
      crud.post(self.params, dao_factory.keyauth_credentials)
    end
  }
}

See the complete Admin API of the Key-Auth plugin for an extended version of this example.

Back to TOC

Next: Write tests for your plugin