diff options
Diffstat (limited to 'doc/src/guide/rest_handlers.ezdoc')
| -rw-r--r-- | doc/src/guide/rest_handlers.ezdoc | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/doc/src/guide/rest_handlers.ezdoc b/doc/src/guide/rest_handlers.ezdoc new file mode 100644 index 0000000..ee3e5aa --- /dev/null +++ b/doc/src/guide/rest_handlers.ezdoc @@ -0,0 +1,135 @@ +::: REST handlers + +REST is implemented in Cowboy as a protocol upgrade. Once upgraded, +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 requests. + +:: Initialization + +First, the `init/3` callback is called. This callback is common +to all handlers. To use REST for the current request, this function +must return an `upgrade` tuple. + +``` erlang +init({tcp, http}, Req, Opts) -> + {upgrade, protocol, cowboy_rest}. +``` + +Cowboy will then switch to the REST protocol and start executing +the state machine, starting from `rest_init/2` if it's defined, +and ending with `rest_terminate/2` also if 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. + +When the request starts being processed, Cowboy will call the +`rest_init/2` function if it is defined, with the Req object +and the handler options as arguments. This function must return +`{ok, Req, State}` where `State` is the handler's state that all +subsequent callbacks will receive. + +At the end of every request, the special callback `rest_terminate/2` +will be called if it is defined. It cannot be used to send a reply, +and must always return `ok`. + +All other callbacks are resource callbacks. They all take two +arguments, the Req object and the State, and return a three-element +tuple of the form `{Value, Req, State}`. + +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. + +All callbacks can also return `{halt, Req, State}` to stop execution +of the request, at which point `rest_terminate/2` will be called. + +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_content_type `true` +| 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 |