diff options
authorLoïc Hoguin <[email protected]>2013-04-11 21:52:09 +0200
committerLoïc Hoguin <[email protected]>2013-04-11 22:25:36 +0200
commit23aa1314fc575d0992e7b9b0bb2cf9dc657ac708 (patch)
parentae45cecfcd2b9291d34ed1897b50b192018b517d (diff)
First draft of the REST chapter in the guide
1 files changed, 82 insertions, 2 deletions
diff --git a/guide/rest_handlers.md b/guide/rest_handlers.md
index 62f0ba1..1eccc65 100644
--- a/guide/rest_handlers.md
+++ b/guide/rest_handlers.md
@@ -25,9 +25,89 @@ Not done yet. Feel free to use the one that is currently being worked on.
-Please see the Webmachine documentation at this time.
+All callbacks are optional. Some may become mandatory depending
+on what other defined callbacks return. The flow diagram should
+be a pretty good resource 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 flow diagram to find out the result of each return
+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, an
+empty column means there is no default value for this callback.
+| Callback name | Default value |
+| ---------------------- | ------------------------- |
+| allowed_methods | `[<<"GET">>, <<"HEAD">>]` |
+| allow_missing_post | `true` |
+| charsets_provided | skip |
+| content_types_accepted | |
+| content_types_provided | |
+| 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 | |
+| 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.
-Please see the examples at this time.
+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.