aboutsummaryrefslogtreecommitdiffstats
path: root/guide/rest_handlers.md
diff options
context:
space:
mode:
Diffstat (limited to 'guide/rest_handlers.md')
-rw-r--r--guide/rest_handlers.md30
1 files changed, 8 insertions, 22 deletions
diff --git a/guide/rest_handlers.md b/guide/rest_handlers.md
index cfb7a38..87991a0 100644
--- a/guide/rest_handlers.md
+++ b/guide/rest_handlers.md
@@ -1,22 +1,14 @@
REST handlers
=============
-Purpose
--------
-
-REST is a set of constraints that, when applied to HTTP, dictates how
-resources must behave. It is the recommended way to handle requests
-with Cowboy.
-
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.
-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.
+The REST handler is the recommended way to handle requests.
-Usage
------
+Initialization
+--------------
Like Websocket, REST is a sub-protocol of HTTP. It therefore
requires a protocol upgrade.
@@ -27,16 +19,9 @@ init({tcp, http}, Req, Opts) ->
```
Cowboy will then switch to the REST protocol and start executing
-the flow diagram, starting from `rest_init/2` if it's defined,
+the state machine, starting from `rest_init/2` if it's defined,
and ending with `rest_terminate/2` also if defined.
-Flow diagram
-------------
-
-Not done yet. Feel free to use the one that is currently being worked on.
-
- * https://github.com/extend/cowboy/pull/364
-
Methods
-------
@@ -50,8 +35,9 @@ Callbacks
---------
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.
+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
@@ -69,7 +55,7 @@ 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
+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