Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.2.x (latest)
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Older Enterprise versions (2.1-2.5)
  • Older OSS versions (2.1-2.5)
  • Archive (pre-2.1)
    • Overview of Kong Gateway
    • Version Support Policy
    • Stages of Software Availability
    • Changelog
    • Overview
    • Kubernetes
    • Helm
    • OpenShift with Helm
    • Docker
    • Amazon Linux
    • CentOS
    • Debian
    • RHEL
    • Ubuntu
    • Migrating from OSS to EE
    • Upgrade Kong Gateway
    • Upgrade Kong Gateway OSS
      • Configuring a Service
      • Configuring a gRPC Service
      • Enabling Plugins
      • Adding Consumers
      • Prepare to Administer
      • Expose your Services
      • Protect your Services
      • Improve Performance
      • Secure Services
      • Set Up Intelligent Load Balancing
      • Manage Administrative Teams
      • Publish, Locate, and Consume Services
    • Running Kong as a Non-Root User
    • Resource Sizing Guidelines
      • Deploy Kong Gateway in Hybrid Mode
    • Kubernetes Deployment Options
    • Control Kong Gateway through systemd
    • Performance Testing Framework
    • DNS Considerations
    • Default Ports
      • Access Your License
      • Deploy Your License
      • Monitor License Usage
      • Start Kong Gateway Securely
      • Keyring and Data Encryption
      • Kong Security Update Process
        • Getting Started
        • Advanced Usage
          • Environment Variables
          • AWS Secrets Manager
          • GCP Secrets Manager
          • Hashicorp Vault
        • Reference Format
      • Authentication Reference
        • OpenID Connect with Curity
        • OpenID Connect with Azure AD
        • OpenID Connect with Google
        • OpenID Connect with Okta
        • OpenID Connect with Auth0
        • OpenID Connect with Cognito
        • OpenID Connect Plugin Reference
      • Allowing Multiple Authentication Methods
        • Create a Super Admin
        • Configure Networking
        • Configure Kong Manager to Send Email
        • Reset Passwords and RBAC Tokens
        • Configure Workspaces
        • Basic Auth
        • LDAP
        • OIDC
        • Sessions
        • Add a Role
        • Add a User
        • Add an Admin
      • Mapping LDAP Service Directory Groups to Kong Roles
    • Configure gRPC Plugins
    • GraphQL Quickstart
    • Logging Reference
    • Network and Firewall
    • Overview
    • Enable the Dev Portal
    • Structure and File Types
    • Portal API Documentation
    • Working with Templates
    • Using the Editor
        • Basic Auth
        • Key Auth
        • OIDC
        • Sessions
        • Adding Custom Registration Fields
      • SMTP
      • Workspaces
      • Manage Developers
      • Developer Roles and Content Permissions
        • Authorization Provider Strategy
        • Enable Application Registration
        • Enable Key Authentication for Application Registration
        • External OAuth2 Support
        • Set up Okta and Kong for external OAuth
        • Set Up Azure AD and Kong for External Authentication
        • Manage Applications
      • Easy Theme Editing
      • Migrating Templates Between Workspaces
      • Markdown Rendering Module
      • Customizing Portal Emails
      • Adding and Using JavaScript Assets
      • Single Page App in Dev Portal
      • Alternate OpenAPI Renderer
    • Helpers CLI
      • Metrics
      • Reports
      • Vitals with InfluxDB
      • Vitals with Prometheus
      • Estimate Vitals Storage in PostgreSQL
    • Prometheus plugin
    • Zipkin plugin
      • DB-less Mode
      • Declarative Configuration
      • Supported Content Types
      • Information Routes
      • Health Routes
      • Tags
      • Service Object
      • Route Object
      • Consumer Object
      • Plugin Object
      • Certificate Object
      • CA Certificate Object
      • SNI Object
      • Upstream Object
      • Target Object
      • Vaults Beta
        • Licenses Reference
        • Licenses Examples
        • Workspaces Reference
        • Workspace Examples
        • RBAC Reference
        • RBAC Examples
        • API Reference
        • Examples
      • Developers
        • API Reference
        • Examples
        • Event Hooks Reference
        • Examples
      • Audit Logging
      • Keyring and Data Encryption
      • Securing the Admin API
    • DB-less and Declarative Configuration
    • Configuration Reference
    • CLI Reference
    • Load Balancing Reference
    • Proxy Reference
    • Rate Limiting Library
    • Health Checks and Circuit Breakers Reference
    • Clustering Reference
      • kong.client
      • kong.client.tls
      • kong.cluster
      • kong.ctx
      • kong.ip
      • kong.log
      • kong.nginx
      • kong.node
      • kong.request
      • kong.response
      • kong.router
      • kong.service
      • kong.service.request
      • kong.service.response
      • kong.table
      • kong.vault
      • Introduction
      • File structure
      • Implementing custom logic
      • Plugin configuration
      • Accessing the datastore
      • Storing custom entities
      • Caching custom entities
      • Extending the Admin API
      • Writing tests
      • (un)Installing your plugin
    • Plugins in Other Languages
    • File Permissions Reference

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Module
  • Add endpoints to the Admin API
Kong Gateway
2.8.x
  • Home
  • Kong Gateway
  • Plugin Development
  • Plugin Development - Extending the Admin API
You are browsing documentation for an outdated 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 via kong.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 hits path, before any other function is invoked.
    • One or more functions can be indexed with HTTP method names, like GET or PUT. These functions will be executed when the appropriate HTTP method and path is matched. If a before function is present on the path, it will be executed first. Keep in mind that before functions can use kong.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 a before or a “http method”) throws an error. If not present, then Kong will use a default error handler to return the errors.

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. On 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 several endpoints-provided utilities (endpoints.handle_error) as well as PDK functions (kong.response.exit). It also populates self.consumer for the subsequent functions to use.
  • The GET function is built entirely using endpoints. This is possible because the before has “prepared” things in advance, like self.consumer.
  • The PUT function populates self.args.post.consumer before calling the endpoints-provided put_entity_endpoint function.

Previous Plugin Development - Caching Custom Entities
Next Plugin Development - Writing tests
Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023