From 25e93c91878b7f8536764b06d2cb72020031acd1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Tue, 18 Feb 2025 09:51:22 +0100
Subject: Cowboy 2.13.0

---
 docs/en/cowboy/2.13/guide/rest_handlers.asciidoc | 148 +++++++++++++++++++++++
 1 file changed, 148 insertions(+)
 create mode 100644 docs/en/cowboy/2.13/guide/rest_handlers.asciidoc

(limited to 'docs/en/cowboy/2.13/guide/rest_handlers.asciidoc')

diff --git a/docs/en/cowboy/2.13/guide/rest_handlers.asciidoc b/docs/en/cowboy/2.13/guide/rest_handlers.asciidoc
new file mode 100644
index 00000000..19a98596
--- /dev/null
+++ b/docs/en/cowboy/2.13/guide/rest_handlers.asciidoc
@@ -0,0 +1,148 @@
+[[rest_handlers]]
+== REST handlers
+
+REST is implemented in Cowboy as a sub protocol. The request
+is handled as a state machine with many optional callbacks
+describing the resource and modifying the machine's behavior.
+
+The REST handler is the recommended way to handle HTTP requests.
+
+=== Initialization
+
+First, the `init/2` callback is called. This callback is common
+to all handlers. To use REST for the current request, this function
+must return a `cowboy_rest` tuple.
+
+[source,erlang]
+----
+init(Req, State) ->
+    {cowboy_rest, Req, State}.
+----
+
+Cowboy will then switch to the REST protocol and start executing
+the state machine.
+
+After reaching the end of the flowchart, the `terminate/3` callback
+will be called if it is defined.
+
+=== Methods
+
+The REST component has code for handling the following HTTP methods:
+HEAD, GET, POST, PATCH, PUT, DELETE and OPTIONS.
+
+Other methods can be accepted, however they have no specific callback
+defined for them at this time.
+
+=== Callbacks
+
+All callbacks are optional. Some may become mandatory depending
+on what other defined callbacks return. The various flowcharts
+in the next chapter should be a useful to determine which callbacks
+you need.
+
+All callbacks take two arguments, the Req object and the State,
+and return a three-element tuple of the form `{Value, Req, State}`.
+
+Nearly all callbacks can also return `{stop, Req, State}` to
+stop execution of the request, and
+`{{switch_handler, Module}, Req, State}` or
+`{{switch_handler, Module, Opts}, Req, State}` to switch to
+a different handler type. The exceptions are `expires`
+`generate_etag`, `last_modified` and `variances`.
+
+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 flowcharts to find out the result of each return
+value.
+
+In the following table, "skip" means the callback is entirely skipped
+if it is undefined, moving directly to the next step. Similarly,
+"none" means there is no default value for this callback.
+
+[cols="<,^",options="header"]
+|===
+| Callback name          | Default value
+| allowed_methods        | `[<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]`
+| allow_missing_post     | `true`
+| charsets_provided      | skip
+| content_types_accepted | none
+// @todo Space required for the time being: https://github.com/spf13/hugo/issues/2398
+| content_types_provided | `[{{ <<"text">>, <<"html">>, '*'}, to_html}]`
+| delete_completed       | `true`
+| delete_resource        | `false`
+| expires                | `undefined`
+| forbidden              | `false`
+| generate_etag          | `undefined`
+| is_authorized          | `true`
+| is_conflict            | `false`
+| known_methods          | `[<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]`
+| languages_provided     | skip
+| last_modified          | `undefined`
+| malformed_request      | `false`
+| moved_permanently      | `false`
+| moved_temporarily      | `false`
+| multiple_choices       | `false`
+| options                | `ok`
+| previously_existed     | `false`
+| ranges_provided        | skip
+| range_satisfiable      | `true`
+| rate_limited           | `false`
+| resource_exists        | `true`
+| service_available      | `true`
+| uri_too_long           | `false`
+| valid_content_headers  | `true`
+| valid_entity_length    | `true`
+| variances              | `[]`
+|===
+
+As you can see, Cowboy tries to move on with the request whenever
+possible by using well thought out default values.
+
+In addition to these, there can be any number of user-defined
+callbacks that are specified through `content_types_accepted/2`,
+`content_types_provided/2` or `ranges_provided/2`. They can take
+any name (except `auto` for range callbacks), however
+it is recommended to use a separate prefix for the callbacks of
+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 values to the Req object at various
+points of the execution. You can retrieve them by matching the
+Req object directly. The values are defined in the following table:
+
+[cols="<,<",options="header"]
+|===
+| Key        | Details
+| media_type | The content-type negotiated for the response entity
+| language   | The language negotiated for the response entity
+| charset    | The charset negotiated for the response entity
+| range      | The range selected for the ranged response
+|===
+
+They can be used to send a proper body with the response to a
+request that used a method other than HEAD or GET.
+
+=== Response headers
+
+Cowboy will set response headers automatically over the execution
+of the REST code. They are listed in the following table.
+
+[cols="<,<",options="header"]
+|===
+| Header name      | Details
+| accept-ranges    | Range units accepted by the resource
+| allow            | HTTP methods allowed by the resource
+| content-language | Language used in the response body
+| content-range    | Range of the content found in the response
+| content-type     | Media type and charset of the response body
+| etag             | Etag of the resource
+| expires          | Expiration date of the resource
+| last-modified    | Last modification date for the resource
+| location         | Relative or absolute URI to the requested resource
+| retry-after      | Delay or time the client should wait before accessing the resource
+| vary             | List of headers that may change the representation of the resource
+| www-authenticate | Authentication information to access the resource
+|===
-- 
cgit v1.2.3

