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.
>
> 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
> * Default value: [{{<<"text">>, <<"html">>, '*'}, to_html}]
>
> Types:
> * Value = [{binary() | {Type, SubType, Params}, ProvideResource}]
> * Type = SubType = binary()
> * Params = '*' | [{binary(), binary()}]
> * AcceptResource = 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.
>
> The `ProvideResource` value is the name of the callback that will
> be called if the content-type matches. It is defined as follow.
>
> * 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() | 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()
> * Default value: undefined
>
> Return the entity tag of the resource.
>
> This value will be sent as the value of the etag header.
### 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.
