Couper Documentation

edge

Endpoint

endpoint blocks define the entry points of Couper. The required label defines the path suffix for the incoming client request. Each endpoint block must produce an explicit or implicit client response.

Block nameContextLabel
endpointServer Block, API Block⚠ required, defines the path suffix for incoming client requests

Endpoint Sequence

If request and/or proxy block definitions are sequential based on their backend_responses.* variable references at load-time they will be executed sequentially. Unexpected responses can be caught with error handling.

Attribute allowed_methods

The default value "*" can be combined with additional methods. Methods are matched case-insensitively. Access-Control-Allow-Methods is only sent in response to a CORS preflight request, if the method requested by Access-Control-Request-Method is an allowed method.

Example:

allowed_methods = ["GET", "POST"]` or `allowed_methods = ["*", "BREW"]

Attribute required_permission

Overrides required_permission in a containing api block. If the value is a string, the same permission applies to all request methods. If there are different permissions for different request methods, use an object with the request methods as keys and string values. Methods not specified in this object are not permitted. "*" is the key for "all other standard methods". Methods other than GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS must be specified explicitly. A value "" means "no permission required". For api blocks with at least two endpoints, all endpoints must have either a) no required_permission set or b) either required_permission or disable_access_control set. Otherwise, a configuration error is thrown.

Example:

required_permission = "read"# orrequired_permission = { post = "write", "*" = "" }# orrequired_permission = default(request.path_params.p, "not_set")

Attributes

NameTypeDefaultDescription
access_control
tuple (string)
[]

Sets predefined access control for this block context.

add_form_params
object
-

Key/value pairs to add form parameters to the upstream request body.

add_query_params
object
-

Key/value pairs to add query parameters to the upstream request URL.

add_request_headers
object
-

Key/value pairs to add as request headers in the upstream request.

add_response_headers
object
-

Key/value pairs to add as response headers in the client response.

allowed_methods
tuple (string)
*

Sets allowed methods overriding a default set in the containing api block. Requests with a method that is not allowed result in an error response with a 405 Method Not Allowed status.

custom_log_fields
object
-

Log fields for custom logging. Inherited by nested blocks.

disable_access_control
tuple (string)
[]

Disables access controls by name.

error_file
string
-

Location of the error file template.

proxy
string
-

References a proxy block in the definitions.

remove_form_params
object
-

List of names to remove form parameters from the upstream request body.

remove_query_params
tuple (string)
[]

List of names to remove query parameters from the upstream request URL.

remove_request_headers
tuple (string)
[]

List of names to remove headers from the upstream request.

remove_response_headers
tuple (string)
[]

List of names to remove headers from the client response.

request_body_limit
string
"64MiB"

Configures the maximum buffer size while accessing request.form_body or request.json_body content. Valid units are: KiB, MiB, GiB.

required_permission
string or object (string)
-

Permission required to use this endpoint (see error type insufficient_permissions).

set_form_params
object
-

Key/value pairs to set query parameters in the upstream request URL.

set_query_params
object
-

Key/value pairs to set query parameters in the upstream request URL.

set_request_headers
object
-

Key/value pairs to set as request headers in the upstream request.

set_response_headers
object
-

Key/value pairs to set as response headers in the client response.

set_response_status
number
-

Modifies the response status code.

Nested Blocks

NameDescription
error_handler

Configures an error handler (zero or more).

proxy

Configures a proxy (zero or more).

request

Configures a request (zero or more).

response

Configures the response (zero or one).