diff options
| -rw-r--r-- | guide/rest_cond.png | bin | 0 -> 111628 bytes | |||
| -rw-r--r-- | guide/rest_conneg.png | bin | 0 -> 78133 bytes | |||
| -rw-r--r-- | guide/rest_delete.png | bin | 0 -> 122185 bytes | |||
| -rw-r--r-- | guide/rest_flowcharts.md | 42 | ||||
| -rw-r--r-- | guide/rest_get_head.png | bin | 0 -> 99942 bytes | |||
| -rw-r--r-- | guide/rest_handlers.md | 30 | ||||
| -rw-r--r-- | guide/rest_options.png | bin | 0 -> 8539 bytes | |||
| -rw-r--r-- | guide/rest_put_post_patch.png | bin | 0 -> 218984 bytes | |||
| -rw-r--r-- | guide/rest_start.png | bin | 0 -> 118210 bytes | |||
| -rw-r--r-- | guide/toc.md | 6 |
10 files changed, 51 insertions, 27 deletions
diff --git a/guide/rest_cond.png b/guide/rest_cond.png Binary files differnew file mode 100644 index 0000000..64cda34 --- /dev/null +++ b/guide/rest_cond.png diff --git a/guide/rest_conneg.png b/guide/rest_conneg.png Binary files differnew file mode 100644 index 0000000..65ecdcf --- /dev/null +++ b/guide/rest_conneg.png diff --git a/guide/rest_delete.png b/guide/rest_delete.png Binary files differnew file mode 100644 index 0000000..56a861c --- /dev/null +++ b/guide/rest_delete.png 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 +----- + + + +OPTIONS method +-------------- + + + +Content negotiation +------------------- + + + +GET and HEAD methods +-------------------- + + + +PUT, POST and PATCH methods +--------------------------- + + + +DELETE method +------------- + + + +Conditional requests +-------------------- + + diff --git a/guide/rest_get_head.png b/guide/rest_get_head.png Binary files differnew file mode 100644 index 0000000..efee892 --- /dev/null +++ b/guide/rest_get_head.png 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 Binary files differnew file mode 100644 index 0000000..90fd6f0 --- /dev/null +++ b/guide/rest_options.png diff --git a/guide/rest_put_post_patch.png b/guide/rest_put_post_patch.png Binary files differnew file mode 100644 index 0000000..f406fcb --- /dev/null +++ b/guide/rest_put_post_patch.png diff --git a/guide/rest_start.png b/guide/rest_start.png Binary files differnew file mode 100644 index 0000000..7f26464 --- /dev/null +++ b/guide/rest_start.png 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 --------- |
