1 files changed, 561 insertions, 0 deletions
diff --git a/doc/src/manual/cowboy_rest.ezdoc b/doc/src/manual/cowboy_rest.ezdoc
new file mode 100644
index 0000000..4d13530
--- /dev/null
+++ b/doc/src/manual/cowboy_rest.ezdoc
@@ -0,0 +1,561 @@
+::: cowboy_rest
+
+The `cowboy_rest` module implements REST semantics on top of
+the HTTP protocol.
+
+This module cannot be described as a behaviour due to most of
+the callbacks it defines being optional. It has the same
+semantics as a behaviour otherwise.
+
+The only mandatory callback is `init/3`, needed to perform
+the protocol upgrade.
+
+:: Types
+
+None.
+
+:: Meta values
+
+: charset
+
+Type: binary()
+
+Negotiated charset.
+
+This value may not be defined if no charset was negotiated.
+
+: language
+
+Type: binary()
+
+Negotiated language.
+
+This value may not be defined if no language was negotiated.
+
+: media_type
+
+Type: {binary(), binary(), '*' | [{binary(), binary()}]}
+
+Negotiated media-type.
+
+The media-type is the content-type, excluding the charset.
+
+This value is always defined after the call to
+`content_types_provided/2`.
+
+:: Callbacks
+
+: init({TransportName, ProtocolName}, Req, Opts)
+	-> {upgrade, protocol, cowboy_rest}
+	| {upgrade, protocol, cowboy_rest, Req, Opts}
+
+Types:
+
+* TransportName = tcp | ssl | atom()
+* ProtocolName = http | atom()
+* Req = cowboy_req:req()
+* Opts = any()
+
+Upgrade the protocol to `cowboy_rest`.
+
+This is the only mandatory callback.
+
+: rest_init(Req, Opts) -> {ok, Req, State}
+
+Types:
+
+* Req = cowboy_req:req()
+* Opts = any()
+* State = any()
+
+Initialize the state for this request.
+
+: rest_terminate(Req, State) -> ok
+
+Types:
+
+* Req = cowboy_req:req()
+* State = any()
+
+Perform any necessary cleanup of the state.
+
+This callback should release any resource currently in use,
+clear any active timer and reset the process to its original
+state, as it might be reused for future requests sent on the
+same connection.
+
+: Callback(Req, State) -> {Value, Req, State} | {halt, Req, State}
+
+Types:
+
+* Callback - one of the REST callbacks described below
+* Req = cowboy_req:req()
+* State = any()
+* Value - see the REST callbacks description below
+
+Please see the REST callbacks description below for details
+on the `Value` type, the default value if the callback is
+not defined, and more general information on when the
+callback is called and what its intended use is.
+
+The `halt` tuple can be returned to stop REST processing.
+It is up to the resource code to send a reply before that,
+otherwise a `204 No Content` will be sent.
+
+:: REST callbacks description
+
+: allowed_methods
+
+* Methods: all
+* Value type: [binary()]
+* Default value: [<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]
+
+Return the list of allowed methods.
+
+Methods are case sensitive. Standard methods are always uppercase.
+
+: allow_missing_post
+
+* Methods: POST
+* Value type: boolean()
+* Default value: true
+
+Return whether POST is allowed when the resource doesn't exist.
+
+Returning `true` here means that a new resource will be
+created. The URL to the created resource should also be
+returned from the `AcceptResource` callback.
+
+: charsets_provided
+
+* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
+* Value type: [binary()]
+* Skip to the next step if undefined
+
+Return the list of charsets the resource provides.
+
+The list must be ordered in order of preference.
+
+If the accept-charset header was not sent, the first charset
+in the list will be selected. Otherwise Cowboy will select
+the most appropriate charset from the list.
+
+The chosen charset will be set in the `Req` object as the meta
+value `charset`.
+
+While charsets are case insensitive, this callback is expected
+to return them as lowercase binary.
+
+: content_types_accepted
+
+* Methods: POST, PUT, PATCH
+* No default
+
+Types:
+
+* Value = [{binary() | {Type, SubType, Params}, AcceptResource}]
+* Type = SubType = binary()
+* Params = '*' | [{binary(), binary()}]
+* AcceptResource = atom()
+
+Return the list of content-types the resource accepts.
+
+The list must be ordered in order of preference.
+
+Each content-type can be given either as a binary string or as
+a tuple containing the type, subtype and parameters.
+
+Cowboy will select the most appropriate content-type from the list.
+If any parameter is acceptable, then the tuple form should be used
+with parameters set to `'*'`. If the parameters value is set to `[]`
+only content-type values with no parameters will be accepted. All
+parameter values are treated in a case sensitive manner except the
+`charset` parameter, if present, which is case insensitive.
+
+This function will be called for POST, PUT and PATCH requests.
+It is entirely possible to define different callbacks for different
+methods if the handling of the request differs. Simply verify
+what the method is with `cowboy_req:method/1` and return a
+different list for each methods.
+
+The `AcceptResource` value is the name of the callback that will
+be called if the content-type matches. It is defined as follow.
+
+* Value type: true | {true, URL} | false
+* No default
+
+Process the request body.
+
+This function should create or update the resource with the
+information contained in the request body. This information
+may be full or partial depending on the request method.
+
+If the request body was processed successfully, `true` or
+`{true, URL}` may be returned. If an URL is provided, the
+response will redirect the client to the location of the
+resource.
+
+If a response body must be sent, the appropriate media-type, charset
+and language can be retrieved using the `cowboy_req:meta/{2,3}`
+functions. The respective keys are `media_type`, `charset`
+and `language`. The body can be set using `cowboy_req:set_resp_body/2`.
+
+: content_types_provided
+
+* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
+* Default value: [{{<<"text">>, <<"html">>, '*'}, to_html}]
+
+Types:
+
+* Value = [{binary() | {Type, SubType, Params}, ProvideResource}]
+* Type = SubType = binary()
+* Params = '*' | [{binary(), binary()}]
+* ProvideResource = atom()
+
+Return the list of content-types the resource provides.
+
+The list must be ordered in order of preference.
+
+Each content-type can be given either as a binary string or as
+a tuple containing the type, subtype and parameters.
+
+Cowboy will select the most appropriate content-type from the list.
+If any parameter is acceptable, then the tuple form should be used
+with parameters set to `'*'`. If the parameters value is set to `[]`
+only content-type values with no parameters will be accepted. All
+parameter values are treated in a case sensitive manner except the
+`charset` parameter, if present, which is case insensitive.
+
+The `ProvideResource` value is the name of the callback that will
+be called if the content-type matches. It will only be called when
+a representation of the resource needs to be returned. It is defined
+as follow.
+
+* Methods: GET, HEAD
+* Value type: iodata() | {stream, Fun} | {stream, Len, Fun} | {chunked, ChunkedFun}
+* No default
+
+Return the response body.
+
+The response body may be provided directly or through a fun.
+If a fun tuple is returned, the appropriate `set_resp_body_fun`
+function will be called. Please refer to the documentation for
+these functions for more information about the types.
+
+The call to this callback happens a good time after the call to
+`content_types_provided/2`, when it is time to start rendering
+the response body.
+
+: delete_completed
+
+* Methods: DELETE
+* Value type: boolean()
+* Default value: true
+
+Return whether the delete action has been completed.
+
+This function should return `false` if there is no guarantee
+that the resource gets deleted immediately from the system,
+including from any internal cache.
+
+When this function returns `false`, a `202 Accepted`
+response will be sent instead of a `200 OK` or `204 No Content`.
+
+: delete_resource
+
+* Methods: DELETE
+* Value type: boolean()
+* Default value: false
+
+Delete the resource.
+
+The value returned indicates if the action was successful,
+regardless of whether the resource is immediately deleted
+from the system.
+
+: expires
+
+* Methods: GET, HEAD
+* Value type: calendar:datetime() | binary() | undefined
+* Default value: undefined
+
+Return the date of expiration of the resource.
+
+This date will be sent as the value of the expires header.
+
+: forbidden
+
+* Methods: all
+* Value type: boolean()
+* Default value: false
+
+Return whether access to the resource is forbidden.
+
+A `403 Forbidden` response will be sent if this
+function returns `true`. This status code means that
+access is forbidden regardless of authentication,
+and that the request shouldn't be repeated.
+
+: generate_etag
+
+* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
+* Value type: binary() | {weak | strong, binary()}
+* Default value: undefined
+
+Return the entity tag of the resource.
+
+This value will be sent as the value of the etag header.
+
+If a binary is returned, then the value will be parsed
+to the tuple form automatically. The value must be in
+the same format as the etag header, including quotes.
+
+: is_authorized
+
+* Methods: all
+* Value type: true | {false, AuthHeader}
+* Default value: true
+
+Return whether the user is authorized to perform the action.
+
+This function should be used to perform any necessary
+authentication of the user before attempting to perform
+any action on the resource.
+
+If the authentication fails, the value returned will be sent
+as the value for the www-authenticate header in the
+`401 Unauthorized` response.
+
+: is_conflict
+
+* Methods: PUT
+* Value type: boolean()
+* Default value: false
+
+Return whether the put action results in a conflict.
+
+A `409 Conflict` response will be sent if this function
+returns `true`.
+
+: known_content_type
+
+* Methods: all
+* Value type: boolean()
+* Default value: true
+
+Return whether the content-type is known.
+
+This function determines if the server understands the
+content-type, regardless of its use by the resource.
+
+: known_methods
+
+* Methods: all
+* Value type: [binary()]
+* Default value: [<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]
+
+Return the list of known methods.
+
+The full list of methods known by the server should be
+returned, regardless of their use in the resource.
+
+The default value lists the methods Cowboy knows and
+implement in `cowboy_rest`.
+
+Methods are case sensitive. Standard methods are always uppercase.
+
+: languages_provided
+
+* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
+* Value type: [binary()]
+* Skip to the next step if undefined
+
+Return the list of languages the resource provides.
+
+The list must be ordered in order of preference.
+
+If the accept-language header was not sent, the first language
+in the list will be selected. Otherwise Cowboy will select
+the most appropriate language from the list.
+
+The chosen language will be set in the `Req` object as the meta
+value `language`.
+
+While languages are case insensitive, this callback is expected
+to return them as lowercase binary.
+
+: last_modified
+
+* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
+* Value type: calendar:datetime()
+* Default value: undefined
+
+Return the date of last modification of the resource.
+
+This date will be used to test against the if-modified-since
+and if-unmodified-since headers, and sent as the last-modified
+header in the response of GET and HEAD requests.
+
+: malformed_request
+
+* Methods: all
+* Value type: boolean()
+* Default value: false
+
+Return whether the request is malformed.
+
+Cowboy has already performed all the necessary checks
+by the time this function is called, so few resources
+are expected to implement it.
+
+The check is to be done on the request itself, not on
+the request body, which is processed later.
+
+: moved_permanently
+
+* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
+* Value type: {true, URL} | false
+* Default value: false
+
+Return whether the resource was permanently moved.
+
+If it was, its new URL is also returned and sent in the
+location header in the response.
+
+: moved_temporarily
+
+* Methods: GET, HEAD, POST, PATCH, DELETE
+* Value type: {true, URL} | false
+* Default value: false
+
+Return whether the resource was temporarily moved.
+
+If it was, its new URL is also returned and sent in the
+location header in the response.
+
+: multiple_choices
+
+* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
+* Value type: boolean()
+* Default value: false
+
+Return whether there are multiple representations of the resource.
+
+This function should be used to inform the client if there
+are different representations of the resource, for example
+different content-type. If this function returns `true`,
+the response body should include information about these
+different representations using `cowboy_req:set_resp_body/2`.
+The content-type of the response should be the one previously
+negociated and that can be obtained by calling
+`cowboy_req:meta(media_type, Req)`.
+
+: options
+
+* Methods: OPTIONS
+* Value type: ok
+* Default value: ok
+
+Handle a request for information.
+
+The response should inform the client the communication
+options available for this resource.
+
+By default, Cowboy will send a `200 OK` response with the
+allow header set.
+
+: previously_existed
+
+* Methods: GET, HEAD, POST, PATCH, DELETE
+* Value type: boolean()
+* Default value: false
+
+Return whether the resource existed previously.
+
+: resource_exists
+
+* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
+* Value type: boolean()
+* Default value: true
+
+Return whether the resource exists.
+
+If it exists, conditional headers will be tested before
+attempting to perform the action. Otherwise, Cowboy will
+check if the resource previously existed first.
+
+: service_available
+
+* Methods: all
+* Value type: boolean()
+* Default value: true
+
+Return whether the service is available.
+
+This function can be used to test that all relevant backend
+systems are up and able to handle requests.
+
+A `503 Service Unavailable` response will be sent if this
+function returns `false`.
+
+: uri_too_long
+
+* Methods: all
+* Value type: boolean()
+* Default value: false
+
+Return whether the requested URI is too long.
+
+Cowboy has already performed all the necessary checks
+by the time this function is called, so few resources
+are expected to implement it.
+
+A `414 Request-URI Too Long` response will be sent if this
+function returns `true`.
+
+: valid_content_headers
+
+* Methods: all
+* Value type: boolean()
+* Default value: true
+
+Return whether the content-* headers are valid.
+
+This also applies to the transfer-encoding header. This
+function must return `false` for any unknown content-*
+headers, or if the headers can't be understood. The
+function `cowboy_req:parse_header/2` can be used to
+quickly check the headers can be parsed.
+
+A `501 Not Implemented` response will be sent if this
+function returns `false`.
+
+: valid_entity_length
+
+* Methods: all
+* Value type: boolean()
+* Default value: true
+
+Return whether the request body length is within acceptable boundaries.
+
+A `413 Request Entity Too Large` response will be sent if this
+function returns `false`.
+
+: variances
+
+* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
+* Value type: [binary()]
+* Default value: []
+
+Return the list of headers that affect the representation of the resource.
+
+These request headers return the same resource but with different
+parameters, like another language or a different content-type.
+
+Cowboy will automatically add the accept, accept-language and
+accept-charset headers to the list if the respective functions
+were defined in the resource.
+
+This operation is performed right before the `resource_exists/2`
+callback. All responses past that point will contain the vary
+header which holds this list.