First draft of the REST chapter in the guide

guide/rest_handlers.md

@@ -25,9 +25,89 @@ Not done yet. Feel free to use the one that is currently being worked on.
 Callbacks
 ---------
 
-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
+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, 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.
 
 Usage
 -----
 
-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.