From 15d6172d27e1e5fc0435f00eb17faa8f79ccfba1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 28 Dec 2016 15:21:25 +0100 Subject: Update docs --- docs/en/cowboy/2.0/guide/resource_design.asciidoc | 9 +- .../en/cowboy/2.0/guide/resource_design/index.html | 9 +- docs/en/cowboy/2.0/manual/cowboy_rest/index.html | 1551 +++++++------------- 3 files changed, 499 insertions(+), 1070 deletions(-) (limited to 'docs/en/cowboy') diff --git a/docs/en/cowboy/2.0/guide/resource_design.asciidoc b/docs/en/cowboy/2.0/guide/resource_design.asciidoc index 691953f1..2325b9f2 100644 --- a/docs/en/cowboy/2.0/guide/resource_design.asciidoc +++ b/docs/en/cowboy/2.0/guide/resource_design.asciidoc @@ -164,11 +164,10 @@ implement the `moved_permanently` callback. === The request -Do we need to perform extra checks to make sure the request -is valid? Cowboy will do many checks when receiving the -request already, do we need more? Note that this only -applies to the request-line and headers of the request, -and not the body. Implement `malformed_request`. +Do you need to read the query string? Individual headers? +Implement `malformed_request` and do all the parsing and +validation in this function. Note that the body should not +be read at this point. May there be a request body? Will I know its size? What's the maximum size of the request body I'm willing diff --git a/docs/en/cowboy/2.0/guide/resource_design/index.html b/docs/en/cowboy/2.0/guide/resource_design/index.html index 895f22b3..0b4fbb52 100644 --- a/docs/en/cowboy/2.0/guide/resource_design/index.html +++ b/docs/en/cowboy/2.0/guide/resource_design/index.html @@ -217,11 +217,10 @@ implement the moved_permanently callback.

The request

-

Do we need to perform extra checks to make sure the request -is valid? Cowboy will do many checks when receiving the -request already, do we need more? Note that this only -applies to the request-line and headers of the request, -and not the body. Implement malformed_request.

+

Do you need to read the query string? Individual headers? +Implement malformed_request and do all the parsing and +validation in this function. Note that the body should not +be read at this point.

May there be a request body? Will I know its size? What’s the maximum size of the request body I’m willing to accept? Implement valid_entity_length.

diff --git a/docs/en/cowboy/2.0/manual/cowboy_rest/index.html b/docs/en/cowboy/2.0/manual/cowboy_rest/index.html index 48fcec78..1ca3844b 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_rest/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_rest/index.html @@ -78,68 +78,66 @@

Description

-

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.

+

The module cowboy_rest implements the HTTP state machine.

+

Implementing REST handlers is not enough to provide a REST +interface; this interface must also follow the REST +constraints including HATEOAS (hypermedia as the engine +of application state).

-

Meta values

-
-
-
-charset = binary() -
-
-

- Negotiated charset. -
- This value may not be defined if no charset was negotiated. -

-
-
-language = binary() -
-
-

- Negotiated language. -
- This value may not be defined if no language was negotiated. -

-
-
-media_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

+

Callbacks

-

The following values may be received as the terminate reason -in the optional terminate/3 callback.

+

REST handlers implement the following interface:

+
+
+
init(Req, State)
+    -> {cowboy_rest, Req, State}
+     | {cowboy_rest, Req, State, hibernate}
+     | {cowboy_rest, Req, State, timeout()}
+     | {cowboy_rest, Req, State, timeout(), hibernate}
+
+Callback(Req, State)
+    -> {Result, Req, State}
+     | {stop, Req, State}
+
+terminate(Reason, Req, State) -> ok  %% optional
+
+Req    :: cowboy_req:req()
+State  :: any()
+Reason :: normal
+        | {crash, error | exit | throw, any()}
+
+Callback - see below
+Result   - see below
+Default  - see below
+

The init/2 callback is common to all handlers. To switch +to the REST handler behavior, it must return cowboy_rest +as the first element of the tuple.

+

The Callback/2 above represents all the REST-specific +callbacks. They are described in the following section +of this manual. REST-specific callbacks differ by their +name, semantics, result and default values. The default +value is the one used when the callback has not been +implemented. They otherwise all follow the same interface.

+

The stop tuple can be returned to stop REST processing. +If no response was sent before then, Cowboy will send a +204 No Content.

+

The optional terminate/3 callback will ultimately be called +with the reason for the termination of the handler. +Cowboy will terminate the process right after this. There +is no need to perform any cleanup in this callback.

+

The following terminate reasons are defined for loop handlers:

normal

- The connection was closed normally. + The handler terminated normally.

@@ -147,1134 +145,567 @@ normal

- 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. + 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

+

REST callbacks

-

Callback(Req, State) → {Value, Req, State} | {stop, Req, State}

-
-
-Callback -
-
-

-One of the REST callbacks described below. -

-
-
-Req = cowboy_req:req() -
-
-

-The Req object. -

-
-
-State = any() -
-
-

-Handler state. -

-
-
-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.

-
-
+

AcceptCallback

+
+
+
AcceptCallback(Req, State) -> {Result, Req, State}
+
+Result  :: true | {true, URI :: iodata()} | false}
+Default  - crash
+

Process the request body.

+

This function should create or update the resource using the +request body.

+

For PUT requests, the body is a representation of the resource +that is being created or replaced.

+

For POST requests, the body is typically application-specific +instructions on how to process the request, but it may also +be a representation of the resource. When creating a new +resource with POST at a different location, return {true, URI} +with URI the new location.

+

For PATCH requests, the body is a series of instructions on +how to update the resource. Patch files or JSON Patch are +examples of such media types.

+

A response body may be sent. The appropriate media type, charset +and language for the response can be retrieved from the Req +object using the media_type, charset and language keys, +respectively. The body can be set using +cowboy_req:set_resp_body(3).

-
-

REST callbacks description

-

allowed_methods

-
-
-Methods -
-
-

-all -

-
-
-Value type -
-
-

-[binary()] -

-
-
-Default value -
-
-

-[<<"GET">>, <<"HEAD">>, <<"OPTIONS">>] -

-
-
+
+
+
allowed_methods(Req, State) -> {Result, Req, State}
+
+Result  :: [binary()]  %% case sensitive
+Default :: [<<"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 -

-
-
+
+
+
allow_missing_post(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: 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.

+created. The URI for the newly created resource should be +returned from the AcceptCallback function.

charsets_provided

-
-
-Methods -
-
-

-GET, HEAD, POST, PUT, PATCH, DELETE -

-
-
-Value type -
-
-

-[binary()] -

-
-
-Default behavior -
-
-

-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.

+
+
+
charsets_provided(Req, State) -> {Result, Req, State}
+
+Result  :: [binary()]  %% lowercase; case insensitive
+Default  - skip this step
+

Return the list of charsets the resource provides in order +of preference.

+

During content negotiation Cowboy will pick the most +appropriate charset for the client. The client advertises +charsets it prefers with the accept-charset header. When +that header is missing, Cowboy picks the first charset +from the resource.

+

Cowboy will add the negotiated charset to the Req object +after this step completes:

+
+
+
req() :: #{
+    charset => binary()  %% lowercase; case insensitive
+}

content_types_accepted

-
-
-Methods -
-
-

-POST, PUT, PATCH -

-
-
-Value type -
-
-

-[{binary() | {Type, SubType, Params}, AcceptResource}] -

-
-
-Default behavior -
-
-

-Crash if undefined. -

-
-
-

With types:

-
    -
  • -

    -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 follows.

-
-
-Value type -
-
-

-true | {true, URL} | false -

-
-
-Default behavior -
-
-

-Crash if undefined. -

-
-
-

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_accepted(Req, State) -> {Result, Req, State}
+
+Result     :: [{binary() | ParsedMime, AcceptCallback :: atom()}]
+ParsedMime :: {Type :: binary(), SubType :: binary(), '*' | Params}
+Params     :: [{Key :: binary(), Value :: binary()}]
+
+Default     - crash
+

Return the list of media types the resource accepts in +order of preference.

+

A media type is made of different parts. The media type +text/html;charset=utf-8 is of type text, subtype html +and has a single parameter charset with value utf-8.

+

Cowboy will match the content-type request header against +the media types the server accepts and select the appropriate +callback. When that header is missing, or when the server does not +accept this media type, the request fails and an error response +is returned. Cowboy will execute the callback immediately otherwise.

+

An empty parameters list [] means that no parameters will be +accepted. When any parameter is acceptable, the tuple form +should be used with parameters as the atom '*'.

+

Cowboy treats all parameters as case sensitive, except for the +charset parameter, which is known to be case insensitive. You +should therefore always provide the charset as a lowercase +binary string.

content_types_provided

-
-
-Methods -
-
-

-GET, HEAD, POST, PUT, PATCH, DELETE -

-
-
-Value type -
-
-

-[{binary() | {Type, SubType, Params}, ProvideResource}] -

-
-
-Default value -
-
-

-[{{ <<"text">>, <<"html">>, '*'}, to_html}] -

-
-
-

With types:

-
    -
  • -

    -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} -

-
-
-Default behavior -
-
-

-Crash if undefined. -

-
-
-

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.

+
+
+
content_types_provided(Req, State) -> {Result, Req, State}
+
+Result     :: [{binary() | ParsedMime, ProvideCallback :: atom()}]
+ParsedMime :: {Type :: binary(), SubType :: binary(), '*' | Params}
+Params     :: [{Key :: binary(), Value :: binary()}]
+
+Default     - [{{ <<"text">>, <<"html">>, '*'}, to_html}]
+

Return the list of media types the resource provides in +order of preference.

+

A media type is made of different parts. The media type +text/html;charset=utf-8 is of type text, subtype html +and has a single parameter charset with value utf-8.

+

During content negotiation Cowboy will pick the most appropriate +media type for the client. The client advertises media types it +prefers with the accept header. When that header is missing, +the content negotiation fails and an error response is returned.

+

The callback given for the selected media type will be called +at the end of the execution of GET and HEAD requests when a +representation must be sent to the client.

+

An empty parameters list [] means that no parameters will be +accepted. When any parameter is acceptable, the tuple form +should be used with parameters as the atom '*'.

+

Cowboy treats all parameters as case sensitive, except for the +charset parameter, which is known to be case insensitive. You +should therefore always provide the charset as a lowercase +binary string.

+

Cowboy will add the negotiated media_type to the Req object +after this step completes:

+
+
+
req() :: #{
+    media_type => ParsedMime
+}

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_completed(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: true
+

Return whether the resource has been fully deleted from the +system, including from any internal cache.

+

Returning false will result in a 202 Accepted response +being sent instead of a 200 OK or 204 No Content.

delete_resource

-
-
-Methods -
-
-

-DELETE -

-
-
-Value type -
-
-

-boolean() -

-
-
-Default value -
-
-

-false -

-
-
+
+
+
delete_resource(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: false

Delete the resource.

-

The value returned indicates if the action was successful, -regardless of whether the resource is immediately deleted -from the system.

+

Cowboy will send an error response when this function +returns false.

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.

+
+
+
expires(Req, State) -> {Result, Req, State}
+
+Result  :: calendar:datetime() | binary() | undefined
+Default :: undefined
+

Return the resource’s expiration date.

forbidden

-
-
-Methods -
-
-

-all -

-
-
-Value type -
-
-

-boolean() -

-
-
-Default value -
-
-

-false -

-
-
+
+
+
forbidden(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: false

Return whether access to the resource is forbidden.

-

A 403 Forbidden response will be sent if this +

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 -

-
-
+
+
+
generate_etag(Req, State) -> {Result, Req, State}
+
+Result  :: binary() | {weak | strong, binary()}
+Default  - no etag value

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.

+

When a binary is returned, the value is automatically +parsed to a tuple. The binary must be in the same +format as the etag header, including quotes.

is_authorized

-
-
-Methods -
-
-

-all -

-
-
-Value type -
-
-

-true | {false, AuthHeader} -

-
-
-Default value -
-
-

-true -

-
-
-

With types:

-
    -
  • -

    -AuthHead = iodata() -

    -
    • -
+
+
+
is_authorized(Req, State) -> {Result, Req, State}
+
+Result  :: true | {false, AuthHeader :: iodata()}
+Default  - 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.

+

When authentication fails, the AuthHeader value will +be sent in the www-authenticate header for 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.

+
+
+
is_conflict(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: false
+

Return whether the PUT request results in a conflict.

+

A 409 Conflict response is sent when true.

known_methods

-
-
-Methods -
-
-

-all -

-
-
-Value type -
-
-

-[binary()] -

-
-
-Default value -
-
-

-[<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>] -

-
-
+
+
+
known_methods(Req, State) -> {Result, Req, State}
+
+Result  :: [binary()]  %% case sensitive
+Default :: [<<"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()] -

-
-
-Default behavior -
-
-

-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.

+
+
+
languages_provided(Req, State) -> {Result, Req, State}
+
+Result  :: [binary()]  %% lowercase; case insensitive
+Default  - skip this step
+

Return the list of languages the resource provides in order +of preference.

+

During content negotiation Cowboy will pick the most +appropriate language for the client. The client advertises +languages it prefers with the accept-language header. When +that header is missing, Cowboy picks the first language +from the resource.

+

Cowboy will add the negotiated language to the Req object +after this step completes:

+
+
+
req() :: #{
+    language => binary()  %% lowercase; case insensitive
+}

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.

+
+
+
last_modified(Req, State) -> {Result, Req, State}
+
+Result  :: calendar:datetime()
+Default  - no last modified value
+

Return the resource’s last modification date.

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.

+header in the response to GET and HEAD requests.

malformed_request

-
-
-Methods -
-
-

-all -

-
-
-Value type -
-
-

-boolean() -

-
-
-Default value -
-
-

-false -

-
-
+
+
+
malformed_request(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: 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.

+

A request is malformed when a component required by the +resource is invalid. This may include the query string +or individual headers. They should be parsed and validated +in this function. The body should not be read at this point.

moved_permanently

-
-
-Methods -
-
-

-GET, HEAD, POST, PUT, PATCH, DELETE -

-
-
-Value type -
-
-

-{true, URL} | false -

-
-
-Default value -
-
-

-false -

-
-
-

With 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_permanently(Req, State) -> {Result, Req, State}
+
+Result  :: {true, URI :: iodata()} | false
+Default :: false
+

Return whether the resource was permanently moved, and +what its new location is.

moved_temporarily

-
-
-Methods -
-
-

-GET, HEAD, POST, PATCH, DELETE -

-
-
-Value type -
-
-

-{true, URL} | false -

-
-
-Default value -
-
-

-false -

-
-
-

With 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.

+
+
+
moved_temporarily(Req, State) -> {Result, Req, State}
+
+Result  :: {true, URI :: iodata()} | false
+Default :: false
+

Return whether the resource was temporarily moved, and +what its new location is.

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).

+
+
+
multiple_choices(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: false
+

Return whether the client should engage in reactive +negotiation.

+

Return true when the server has multiple representations +of a resource, each with their specific identifier, but is +unable to determine which is best for the client. For +example an image might have different sizes and the server +is unable to determine the capabilities of the client.

+

When returning true the server should send a body with +links to the different representations. If the server has +a preferred representation it can send its link inside a +location header.

options

-
-
-Methods -
-
-

-OPTIONS -

-
-
-Value type -
-
-

-ok -

-
-
-Default value -
-
-

-ok -

-
-
-

Handle a request for information.

+
+
+
options(Req, State) -> {ok, Req, State}
+

Respond to an OPTIONS request.

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.

+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 -

-
-
+
+
+
previously_existed(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: false

Return whether the resource existed previously.

+

ProvideCallback

+
+
+
ProvideCallback(Req, State) -> {Result, Req, State}
+
+Result  :: cowboy_req:resp_body()
+Default  - crash
+

Return the response body.

+

The response body can be provided either as the actual data +to be sent or a tuple indicating which file to send.

+

This function is called for both GET and HEAD requests. For +the latter the body is not sent, however.

+

Note that there used to be a way to stream the response body. +It was temporarily removed and will be added back in a later +release.

+
+

resource_exists

-
-
-Methods -
-
-

-GET, HEAD, POST, PUT, PATCH, DELETE -

-
-
-Value type -
-
-

-boolean() -

-
-
-Default value -
-
-

-true -

-
-
+
+
+
resource_exists(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: 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 -

-
-
+
+
+
service_available(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: 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 +

A 503 Service Unavailable response will be sent when this function returns false.

uri_too_long

-
-
-Methods -
-
-

-all -

-
-
-Value type -
-
-

-boolean() -

-
-
-Default value -
-
-

-false -

-
-
+
+
+
uri_too_long(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: 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.

+

This function can be used to further restrict the length +of the URI for this specific resource.

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_content_headers(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: true
+

Return whether the content headers are valid.

+

This callback can be used to reject requests that have +invalid content header values, for example an unsupported +content-encoding.

valid_entity_length

-
-
-Methods -
-
-

-all -

-
-
-Value type -
-
-

-boolean() -

-
-
-Default value -
-
-

-true -

-
-
+
+
+
valid_entity_length(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: true

Return whether the request body length is within acceptable boundaries.

-

A 413 Request Entity Too Large response will be sent if this +

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.

+
+
+
variances(Req, State) -> {Result, Req, State}
+
+Result  :: [binary()]  %% case insensitive
+Default :: []
+

Return the list of request headers that affect the +representation of the resource.

+

Cowboy automatically adds the accept, accept-charset and +accept-language headers when necessary.

+
+
+

See also

+
+

cowboy(7), +cowboy_handler(3)

+
-- cgit v1.2.3