From 4023e7f4e429179fd9c2cce4487c33646c6bd327 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 14 Jan 2016 13:35:25 +0100 Subject: Convert the documentation to Asciidoc A few small revisions were made, and Erlang.mk has been updated. --- doc/src/guide/rest_handlers.ezdoc | 125 -------------------------------------- 1 file changed, 125 deletions(-) delete mode 100644 doc/src/guide/rest_handlers.ezdoc (limited to 'doc/src/guide/rest_handlers.ezdoc') diff --git a/doc/src/guide/rest_handlers.ezdoc b/doc/src/guide/rest_handlers.ezdoc deleted file mode 100644 index e6bb092..0000000 --- a/doc/src/guide/rest_handlers.ezdoc +++ /dev/null @@ -1,125 +0,0 @@ -::: 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, #state{}}. -``` - -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 -- cgit v1.2.3