diff options
Diffstat (limited to 'guide')
| -rw-r--r-- | guide/rest_handlers.md | 49 | ||||
| -rw-r--r-- | guide/toc.md | 5 |
2 files changed, 38 insertions, 16 deletions
diff --git a/guide/rest_handlers.md b/guide/rest_handlers.md index ac11d98..7e8427e 100644 --- a/guide/rest_handlers.md +++ b/guide/rest_handlers.md @@ -15,6 +15,21 @@ describing the resource and modifying the machine's behavior. As the REST handler is still subject to change, the documentation is still thin. This state of affair will be improved in the coming weeks. +Usage +----- + +Like Websocket, REST is a sub-protocol of HTTP. It therefore +requires a protocol upgrade. + +``` erlang +init({tcp, http}, Req, Opts) -> + {upgrade, protocol, cowboy_rest}. +``` + +Cowboy will then switch to the REST protocol and start executing +the flow diagram, starting from `rest_init/2` if it's defined, +and ending with `rest_terminate/2` also if defined. + Flow diagram ------------ @@ -70,7 +85,7 @@ empty column means there is no default value for this callback. | allow_missing_post | `true` | | charsets_provided | skip | | content_types_accepted | | -| content_types_provided | | +| content_types_provided | `[{{<<"text">>, <<"html">>, '*'}, to_html}] ` | | delete_completed | `true` | | delete_resource | `false` | | expires | `undefined` | @@ -106,6 +121,9 @@ each function. For example, `from_html` and `to_html` indicate in the first case that we're accepting a resource given as HTML, and in the second case that we send one as HTML. +Meta data +--------- + Cowboy will set informative meta values at various points of the execution. You can retrieve them using `cowboy_req:meta/{2,3}`. The values are defined in the following table. @@ -119,17 +137,18 @@ The values are defined in the following table. They can be used to reply a response entity to a request with an idempotent method (`POST`, `PUT`, `PATCH`, `DELETE`). -Usage ------ - -Like Websocket, REST is a sub-protocol of HTTP. It therefore -requires a protocol upgrade. - -``` erlang -init({tcp, http}, Req, Opts) -> - {upgrade, protocol, cowboy_rest}. -``` - -Cowboy will then switch to the REST protocol and start executing -the flow diagram, starting from `rest_init/2` if it's defined, -and ending with `rest_terminate/2` also if defined. +Response headers +---------------- + +Cowboy will set response headers automatically over the execution +of the REST code. They are listed in the following table. + +| Header name | Details | +| ---------------- | -------------------------------------------------- | +| content-language | Language used in the response body | +| content-type | Media type and charset of the response body | +| etag | Etag of the resource | +| expires | Expiration date of the resource | +| last-modified | Last modification date for the resource | +| location | Relative or absolute URI to the requested resource | +| vary | List of headers that may change the representation of the resource | diff --git a/guide/toc.md b/guide/toc.md index 44c8e22..f8eeb18 100644 --- a/guide/toc.md +++ b/guide/toc.md @@ -28,9 +28,12 @@ Cowboy User Guide * Usage * [REST handlers](rest_handlers.md) * Purpose + * Usage * Flow diagram + * Methods * Callbacks - * Usage + * Meta data + * Response headers * [Static handlers](static_handlers.md) * Purpose * Usage |