diff options
Diffstat (limited to 'manual/cowboy_rest.md')
| -rw-r--r-- | manual/cowboy_rest.md | 552 |
1 files changed, 552 insertions, 0 deletions
diff --git a/manual/cowboy_rest.md b/manual/cowboy_rest.md new file mode 100644 index 0000000..4d5862a --- /dev/null +++ b/manual/cowboy_rest.md @@ -0,0 +1,552 @@ +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()}] +> * 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. +> +> 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() | {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. + +### 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. |