aboutsummaryrefslogtreecommitdiffstats
path: root/guide
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2014-06-21 18:50:50 +0200
committerLoïc Hoguin <[email protected]>2014-06-21 18:50:50 +0200
commit05503affa8a85bd71f67cbe5580545d18d356f93 (patch)
tree2888dac2efca53fc03ddcb096e9d7cd4750924e4 /guide
parent7b18373943853e08f00341ece92dbf3dd5e2a9b2 (diff)
downloadcowboy-05503affa8a85bd71f67cbe5580545d18d356f93.tar.gz
cowboy-05503affa8a85bd71f67cbe5580545d18d356f93.tar.bz2
cowboy-05503affa8a85bd71f67cbe5580545d18d356f93.zip
Add a stub chapter with all the REST flowcharts
The detailed explanations will be written at a later time.
Diffstat (limited to 'guide')
-rw-r--r--guide/rest_cond.pngbin0 -> 111628 bytes
-rw-r--r--guide/rest_conneg.pngbin0 -> 78133 bytes
-rw-r--r--guide/rest_delete.pngbin0 -> 122185 bytes
-rw-r--r--guide/rest_flowcharts.md42
-rw-r--r--guide/rest_get_head.pngbin0 -> 99942 bytes
-rw-r--r--guide/rest_handlers.md30
-rw-r--r--guide/rest_options.pngbin0 -> 8539 bytes
-rw-r--r--guide/rest_put_post_patch.pngbin0 -> 218984 bytes
-rw-r--r--guide/rest_start.pngbin0 -> 118210 bytes
-rw-r--r--guide/toc.md6
10 files changed, 51 insertions, 27 deletions
diff --git a/guide/rest_cond.png b/guide/rest_cond.png
new file mode 100644
index 0000000..64cda34
--- /dev/null
+++ b/guide/rest_cond.png
Binary files differ
diff --git a/guide/rest_conneg.png b/guide/rest_conneg.png
new file mode 100644
index 0000000..65ecdcf
--- /dev/null
+++ b/guide/rest_conneg.png
Binary files differ
diff --git a/guide/rest_delete.png b/guide/rest_delete.png
new file mode 100644
index 0000000..56a861c
--- /dev/null
+++ b/guide/rest_delete.png
Binary files differ
diff --git a/guide/rest_flowcharts.md b/guide/rest_flowcharts.md
new file mode 100644
index 0000000..1aa4f55
--- /dev/null
+++ b/guide/rest_flowcharts.md
@@ -0,0 +1,42 @@
+REST flowcharts
+===============
+
+This chapter will explain the REST handler state machine through
+a number of different diagrams.
+
+This chapter is still under construction.
+
+Start
+-----
+
+![REST starting flowchart](rest_start.png)
+
+OPTIONS method
+--------------
+
+![REST OPTIONS method flowchart](rest_options.png)
+
+Content negotiation
+-------------------
+
+![REST content negotiation flowchart](rest_conneg.png)
+
+GET and HEAD methods
+--------------------
+
+![REST GET/HEAD methods flowchart](rest_get_head.png)
+
+PUT, POST and PATCH methods
+---------------------------
+
+![REST PUT/POST/PATCH methods flowchart](rest_put_post_patch.png)
+
+DELETE method
+-------------
+
+![REST DELETE method flowchart](rest_delete.png)
+
+Conditional requests
+--------------------
+
+![REST conditional requests flowchart](rest_cond.png)
diff --git a/guide/rest_get_head.png b/guide/rest_get_head.png
new file mode 100644
index 0000000..efee892
--- /dev/null
+++ b/guide/rest_get_head.png
Binary files differ
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
diff --git a/guide/rest_options.png b/guide/rest_options.png
new file mode 100644
index 0000000..90fd6f0
--- /dev/null
+++ b/guide/rest_options.png
Binary files differ
diff --git a/guide/rest_put_post_patch.png b/guide/rest_put_post_patch.png
new file mode 100644
index 0000000..f406fcb
--- /dev/null
+++ b/guide/rest_put_post_patch.png
Binary files differ
diff --git a/guide/rest_start.png b/guide/rest_start.png
new file mode 100644
index 0000000..7f26464
--- /dev/null
+++ b/guide/rest_start.png
Binary files differ
diff --git a/guide/toc.md b/guide/toc.md
index 2bc91b1..db10317 100644
--- a/guide/toc.md
+++ b/guide/toc.md
@@ -34,11 +34,7 @@ REST
* [REST principles](rest_principles.md)
* [Handling REST requests](rest_handlers.md)
- * HEAD/GET requests flowchart
- * POST/PUT/PATCH requests flowchart
- * DELETE requests flowchart
- * OPTIONS requests flowchart
- * Designing a REST API
+ * [REST flowcharts](rest_flowcharts.md)
Multipart
---------