# 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](https://zato.io/docs/admin/enmasse.html) YAML under the `channel_rest` key. This page is the complete field reference - the general enmasse workflow is described in the [enmasse guide](https://zato.io/docs/admin/enmasse.html) and the other object types in the [enmasse reference](https://zato.io/docs/admin/enmasse-reference.html).

## A complete example {#a-complete-example}

```yaml
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 {#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](https://zato.io/docs/dev/rest/url-matching.html) |

## Security {#security}

| Key | What it is |
| --- | --- |
| `security` | The name of one security definition - [Basic Auth](https://zato.io/docs/security/basic-auth.html), [API key](https://zato.io/docs/security/api-keys.html), [bearer token](https://zato.io/docs/security/bearer-tokens/index.html) or [mTLS](https://zato.io/docs/security/mtls/index.html) |
| `groups` | A list of [security group](https://zato.io/docs/dev/rest/security-groups.html) 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](https://zato.io/docs/admin/enmasse.html#import-semantics) are described in the enmasse guide.

## Optional keys {#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](https://zato.io/docs/dev/rest/url-matching.html) |
| `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](https://zato.io/docs/admin/audit-log/index.html) records the channel's traffic |
| `should_include_in_openapi` | `true` | Whether the channel appears in generated [OpenAPI](https://zato.io/docs/dev/rest/openapi.html) documents |
| `gateway_service_list` | none | A list of services callable through this one gateway channel |
| `rate_limiting` | none | The channel's [rate limiting](https://zato.io/docs/admin/guide/rate-limit.html) rules, as a nested mapping |
| `response_cache` | none | The channel's [response cache](https://zato.io/docs/dev/api-management/response-caching.html) configuration, as a nested mapping |

## Deprecation keys {#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 |

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

## Keys that pass through {#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 {#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](https://zato.io/docs/security/quota-tiers.html) is assigned through the security definition, not through the channel - see [quota tiers](https://zato.io/docs/admin/guide/quota-tiers.html)

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.

## See also {#see-also}

- [REST channels](https://zato.io/docs/dev/rest/channels.html) - What each channel\_rest key configures in the Dashboard
- [URL path matching](https://zato.io/docs/dev/rest/url-matching.html) - The url\_path, method and parameter keys in depth
- [Security groups](https://zato.io/docs/dev/rest/security-groups.html) - The groups the groups key assigns to a channel
- [API versioning](https://zato.io/docs/dev/rest/versioning.html) - The deprecation keys and the headers they produce

## Learn more {#learn-more}

- [REST integration overview](https://zato.io/integrations/rest/) - Start here to see how teams build REST integrations
- [In-depth API tutorial](https://zato.io/tutorials/main/01.html) - Master architectural patterns for production-ready integrations
- [Modern REST API tutorial](https://zato.io/tutorials/rest-api/python.html) - Design, build and secure REST APIs with Python