From 05503affa8a85bd71f67cbe5580545d18d356f93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Sat, 21 Jun 2014 18:50:50 +0200 Subject: Add a stub chapter with all the REST flowcharts The detailed explanations will be written at a later time. --- guide/rest_cond.png | Bin 0 -> 111628 bytes guide/rest_conneg.png | Bin 0 -> 78133 bytes guide/rest_delete.png | Bin 0 -> 122185 bytes guide/rest_flowcharts.md | 42 ++++++++++++++++++++++++++++++++++++++++++ guide/rest_get_head.png | Bin 0 -> 99942 bytes guide/rest_handlers.md | 30 ++++++++---------------------- guide/rest_options.png | Bin 0 -> 8539 bytes guide/rest_put_post_patch.png | Bin 0 -> 218984 bytes guide/rest_start.png | Bin 0 -> 118210 bytes guide/toc.md | 6 +----- 10 files changed, 51 insertions(+), 27 deletions(-) create mode 100644 guide/rest_cond.png create mode 100644 guide/rest_conneg.png create mode 100644 guide/rest_delete.png create mode 100644 guide/rest_flowcharts.md create mode 100644 guide/rest_get_head.png create mode 100644 guide/rest_options.png create mode 100644 guide/rest_put_post_patch.png create mode 100644 guide/rest_start.png (limited to 'guide') diff --git a/guide/rest_cond.png b/guide/rest_cond.png new file mode 100644 index 0000000..64cda34 Binary files /dev/null and b/guide/rest_cond.png differ diff --git a/guide/rest_conneg.png b/guide/rest_conneg.png new file mode 100644 index 0000000..65ecdcf Binary files /dev/null and b/guide/rest_conneg.png differ diff --git a/guide/rest_delete.png b/guide/rest_delete.png new file mode 100644 index 0000000..56a861c Binary files /dev/null and b/guide/rest_delete.png 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 Binary files /dev/null and b/guide/rest_get_head.png 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 Binary files /dev/null and b/guide/rest_options.png differ diff --git a/guide/rest_put_post_patch.png b/guide/rest_put_post_patch.png new file mode 100644 index 0000000..f406fcb Binary files /dev/null and b/guide/rest_put_post_patch.png differ diff --git a/guide/rest_start.png b/guide/rest_start.png new file mode 100644 index 0000000..7f26464 Binary files /dev/null and b/guide/rest_start.png 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 --------- -- cgit v1.2.3