mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-15 04:30:25 +00:00
999dc5b7c1
Now everywhere in Cowboy when we want to stop something we return a 'stop' tuple instead of one of the many choices depending on context that we had before. This particular change affects middlewares, sub protocols and REST handlers which were using 'halt' to stop processing.
125 lines
4.2 KiB
Text
125 lines
4.2 KiB
Text
::: REST handlers
|
|
|
|
REST is implemented in Cowboy as a sub protocol. The request
|
|
is handled as a state machine with many optional callbacks
|
|
describing the resource and modifying the machine's behavior.
|
|
|
|
The REST handler is the recommended way to handle HTTP requests.
|
|
|
|
:: Initialization
|
|
|
|
First, the `init/2` callback is called. This callback is common
|
|
to all handlers. To use REST for the current request, this function
|
|
must return a `cowboy_rest` tuple.
|
|
|
|
``` erlang
|
|
init(Req, Opts) ->
|
|
{cowboy_rest, Req, Opts}.
|
|
```
|
|
|
|
Cowboy will then switch to the REST protocol and start executing
|
|
the state machine.
|
|
|
|
After reaching the end of the flowchart, the `terminate/3` callback
|
|
will be called if it is defined.
|
|
|
|
:: Methods
|
|
|
|
The REST component has code for handling the following HTTP methods:
|
|
HEAD, GET, POST, PATCH, PUT, DELETE and OPTIONS.
|
|
|
|
Other methods can be accepted, however they have no specific callback
|
|
defined for them at this time.
|
|
|
|
:: Callbacks
|
|
|
|
All callbacks are optional. Some may become mandatory depending
|
|
on what other defined callbacks return. The various flowcharts
|
|
in the next chapter should be a useful to determine which callbacks
|
|
you need.
|
|
|
|
All callbacks take two arguments, the Req object and the State,
|
|
and return a three-element tuple of the form `{Value, Req, State}`.
|
|
|
|
All callbacks can also return `{stop, Req, State}` to stop execution
|
|
of the request.
|
|
|
|
The following table summarizes the callbacks and their default values.
|
|
If the callback isn't defined, then the default value will be used.
|
|
Please look at the flowcharts to find out the result of each return
|
|
value.
|
|
|
|
In the following table, "skip" means the callback is entirely skipped
|
|
if it is undefined, moving directly to the next step. Similarly,
|
|
"none" means there is no default value for this callback.
|
|
|
|
|| Callback name Default value
|
|
|
|
|
| allowed_methods `[<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]`
|
|
| allow_missing_post `true`
|
|
| charsets_provided skip
|
|
| content_types_accepted none
|
|
| content_types_provided `[{{<<"text">>, <<"html">>, '*'}, to_html}] `
|
|
| delete_completed `true`
|
|
| delete_resource `false`
|
|
| expires `undefined`
|
|
| forbidden `false`
|
|
| generate_etag `undefined`
|
|
| is_authorized `true`
|
|
| is_conflict `false`
|
|
| known_methods `[<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]`
|
|
| languages_provided skip
|
|
| last_modified `undefined`
|
|
| malformed_request `false`
|
|
| moved_permanently `false`
|
|
| moved_temporarily `false`
|
|
| multiple_choices `false`
|
|
| options `ok`
|
|
| previously_existed `false`
|
|
| resource_exists `true`
|
|
| service_available `true`
|
|
| uri_too_long `false`
|
|
| valid_content_headers `true`
|
|
| valid_entity_length `true`
|
|
| variances `[]`
|
|
|
|
As you can see, Cowboy tries to move on with the request whenever
|
|
possible by using well thought out default values.
|
|
|
|
In addition to these, there can be any number of user-defined
|
|
callbacks that are specified through `content_types_accepted/2`
|
|
and `content_types_provided/2`. They can take any name, however
|
|
it is recommended to use a separate prefix for the callbacks of
|
|
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.
|
|
|
|
|| Meta key Details
|
|
|
|
|
| media_type The content-type negotiated for the response entity.
|
|
| language The language negotiated for the response entity.
|
|
| charset The charset negotiated for the response entity.
|
|
|
|
They can be used to send a proper body with the response to a
|
|
request that used a method other than HEAD or GET.
|
|
|
|
:: 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
|