kong.tools.responses

Kong helper methods to send HTTP responses to clients.

Can be used in the proxy (core/resolver), plugins or Admin API. Most used HTTP status codes and responses are implemented as helper methods.

Usage:

  • local responses = require "kong.tools.responses"
    
    -- In an Admin API endpoint handler, or in one of the plugins' phases.
    -- the `return` keyword is optional since the execution will be stopped
    -- anyways. It simply improves code readability.
    return responses.send_HTTP_OK()
    
    -- Or:
    return responses.send_HTTP_NOT_FOUND("No entity for given id")
    
    -- Raw send() helper:
    return responses.send(418, "This is a teapot")
    

Info:

    Functions

    send (status_code, body, headers) Send a response with any status code or body, Not all status codes are available as sugar methods, this function can be used to send any response.

    Tables

    status_codes Define the most common HTTP status codes for sugar methods.

    Functions


    send

    Send a response with any status code or body, Not all status codes are available as sugar methods, this function can be used to send any response. For status_code=5xx the content parameter should be the description of the error that occurred. For status_code=500 the content will be logged by ngx.log as an ERR. Will call ngx.say and ngx.exit, terminating the current context.
    Parameters:
    • status_code number HTTP status code to send
    • body A string or table which will be the body of the sent response. If table, the response will be encoded as a JSON object. If string, the response will be a JSON object and the string will be contained in the message property.
    • headers table Response headers to send.
    Returns:
    • ngx.exit (Exit current context)
    See also:

    Tables


    status_codes

    Define the most common HTTP status codes for sugar methods. Each of those status will generate a helper method (sugar) attached to this exported module prefixed with send_. Final signature of those methods will be send_<status_code_key>(message, headers). See send for more details on those parameters.
    Fields:
    • HTTP_OK 200 OK
    • HTTP_CREATED 201 Created
    • HTTP_NO_CONTENT 204 No Content
    • HTTP_BAD_REQUEST 400 Bad Request
    • HTTP_UNAUTHORIZED 401 Unauthorized
    • HTTP_FORBIDDEN 403 Forbidden
    • HTTP_NOT_FOUND 404 Not Found
    • HTTP_METHOD_NOT_ALLOWED 405 Method Not Allowed
    • HTTP_CONFLICT 409 Conflict
    • HTTP_UNSUPPORTED_MEDIA_TYPE 415 Unsupported Media Type
    • HTTP_INTERNAL_SERVER_ERROR Internal Server Error
    • HTTP_SERVICE_UNAVAILABLE 503 Service Unavailable
    Usage:
    • return responses.send_HTTP_OK()
    • return responses.HTTP_CREATED("Entity created")
    • return responses.HTTP_INTERNAL_SERVER_ERROR()