diff options
Diffstat (limited to 'doc/src/manual/cowboy_rest.ezdoc')
-rw-r--r-- | doc/src/manual/cowboy_rest.ezdoc | 536 |
1 files changed, 0 insertions, 536 deletions
diff --git a/doc/src/manual/cowboy_rest.ezdoc b/doc/src/manual/cowboy_rest.ezdoc deleted file mode 100644 index 35131c7..0000000 --- a/doc/src/manual/cowboy_rest.ezdoc +++ /dev/null @@ -1,536 +0,0 @@ -::: cowboy_rest - -The `cowboy_rest` module implements REST semantics on top of -the HTTP protocol. - -This module is a sub protocol that defines many callbacks -be implemented by handlers. The `init/2` and `terminate/3` -callbacks are common to all handler types and are documented -in the manual for the ^cowboy_handler module. - -All other callbacks are optional, though some may become -required depending on the return value of previous callbacks. - -:: 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`. - -:: Terminate reasons - -The following values may be received as the terminate reason -in the optional `terminate/3` callback. - -: normal - -The connection was closed normally. - -: {crash, Class, Reason} - -A crash occurred in the handler. `Class` and `Reason` can be -used to obtain more information about the crash. The function -`erlang:get_stacktrace/0` can also be called to obtain the -stacktrace of the process when the crash occurred. - -:: Callbacks - -: Callback(Req, State) -> {Value, Req, State} | {stop, 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 `stop` 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` must -be returned. If the request method is POST, `{true, URL}` may -be returned instead, and Cowboy will redirect the client to -the location of the newly created 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 - -Types: - -* AuthHead = iodata() - -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_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 - -Types: - -* URL = iodata() - -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 - -Types: - -* URL = iodata() - -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. |