Update the REST chapter of the guide

guide/rest_handlers.md

@@ -15,6 +15,21 @@ describing the resource and modifying the machine's behavior.
 As the REST handler is still subject to change, the documentation is
 still thin. This state of affair will be improved in the coming weeks.
 
+Usage
+-----
+
+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.
+
 Flow diagram
 ------------
 
@@ -70,7 +85,7 @@ empty column means there is no default value for this callback.
 | allow_missing_post     | `true`                    |
 | charsets_provided      | skip                      |
 | content_types_accepted |                           |
-| content_types_provided |                           |
+| content_types_provided | `[{{<<"text">>, <<"html">>, '*'}, to_html}] ` |
 | delete_completed       | `true`                    |
 | delete_resource        | `false`                   |
 | expires                | `undefined`               |
@@ -106,6 +121,9 @@ 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.
@@ -119,17 +137,18 @@ The values are defined in the following table.
 They can be used to reply a response entity to a request with
 an idempotent method (`POST`, `PUT`, `PATCH`, `DELETE`).
 
-Usage
+Response headers
------
+----------------
 
-Like Websocket, REST is a sub-protocol of HTTP. It therefore
+Cowboy will set response headers automatically over the execution
-requires a protocol upgrade.
+of the REST code. They are listed in the following table.
 
-``` erlang
+| Header name      | Details                                            |
-init({tcp, http}, Req, Opts) ->
+| ---------------- | -------------------------------------------------- |
-    {upgrade, protocol, cowboy_rest}.
+| content-language | Language used in the response body                 |
-```
+| content-type     | Media type and charset of the response body        |
-
+| etag             | Etag of the resource                               |
-Cowboy will then switch to the REST protocol and start executing
+| expires          | Expiration date of the resource                    |
-the flow diagram, starting from `rest_init/2` if it's defined,
+| last-modified    | Last modification date for the resource            |
-and ending with `rest_terminate/2` also if defined.
+| location         | Relative or absolute URI to the requested resource |
+| vary             | List of headers that may change the representation of the resource |

guide/toc.md

@@ -28,9 +28,12 @@ Cowboy User Guide
    *  Usage
  *  [REST handlers](rest_handlers.md)
    *  Purpose
-   *  Flow diagram
-   *  Callbacks
    *  Usage
+   *  Flow diagram
+   *  Methods
+   *  Callbacks
+   *  Meta data
+   *  Response headers
  *  [Static handlers](static_handlers.md)
    *  Purpose
    *  Usage