Enmasse reference for REST channels

Every channel_rest key that enmasse accepts, with defaults and the ones to avoid.

REST channels are defined in enmasse YAML under the channel_rest key. This page is the complete field reference - the general enmasse workflow is described in the enmasse guide and the other object types in the enmasse reference.

A complete example

channel_rest:

  - name: api.customer.get
    service: demo.rest.get-customer
    url_path: /api/customers/{customer_id}
    method: GET
    data_format: json
    security: My API Credentials

  - name: api.orders.create
    service: demo.rest.create-order
    url_path: /api/orders
    method: POST
    data_format: json
    groups:
      - Partner Applications

Required keys

Key	What it is
`name`	The channel's name, unique among channels
`service`	The service the channel invokes, by its name
`url_path`	The URL path, with optional `{parameters}` per URL path matching

Security

Key	What it is
`security`	The name of one security definition - Basic Auth, API key, bearer token or mTLS
`groups`	A list of security group names, letting many credentials call one channel

The key is security, never security_name - a security_name key is not read and the channel is created with no security attached, silently. Use security or groups.

A channel that already exists in the environment is updated in place on import, one that does not is created - the import semantics are described in the enmasse guide.

Optional keys

Key	Default	What it is
`method`	any method	The one HTTP method the channel accepts
`data_format`	none	Set `json` for channels that parse JSON - there is no implicit default, and a channel without it hands services the raw bytes
`is_active`	`true`	An inactive channel answers 404
`merge_url_params_req`	`true`	Merge path and query parameters into the request, per URL path matching
`url_params_pri`	`qs-over-path`	Which side wins when a name is both in the path and the query string
`is_audit_log_active`	`true`	Whether the audit log records the channel's traffic
`should_include_in_openapi`	`true`	Whether the channel appears in generated OpenAPI documents
`gateway_service_list`	none	A list of services callable through this one gateway channel
`rate_limiting`	none	The channel's rate limiting rules, as a nested mapping
`response_cache`	none	The channel's response cache configuration, as a nested mapping

Deprecation keys

Key	Default	What it is
`is_deprecated`	`false`	Marks the channel deprecated - responses include deprecation headers
`deprecation_sunset`	none	The date the channel stops working, for the `Sunset` header
`deprecation_successor`	none	The URL of the replacement, for the `Link` header

The moment a channel first becomes deprecated, the import stamps the current UTC time as the deprecation start - there is no key to set it by hand.

Keys that pass through

Plain channel attributes not listed above - timeout, content_type, host, pool_size and the like - are applied to the channel as given. timeout and content_type configure the channel's object only and have no effect on how incoming requests are read.

What enmasse cannot set

http_accept and match_slash are configured in the Dashboard only - an enmasse key of either name is silently lost
soap_action is always the empty string for enmasse-created channels
A quota tier is assigned through the security definition, not through the channel - see quota tiers

The object type is channel_rest - no alias works for it, so a file using any other top-level key for REST channels creates nothing and reports nothing.

Page	What it covers
REST channels	What each channel_rest key configures in the Dashboard
URL path matching	The url_path, method and parameter keys in depth
Security groups	The groups the groups key assigns to a channel
API versioning	The deprecation keys and the headers they produce

Learn more

REST integration overview Start here to see how teams build REST integrations

In-depth API tutorial Master architectural patterns for production-ready integrations

Modern REST API tutorial Design, build and secure REST APIs with Python