+ +

cowboy_rest(3)

+ +

Name

cowboy_rest - REST handlers

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.

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

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}

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

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()] +
+
+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.

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_provided

+Methods +: +
+GET, HEAD, POST, PUT, PATCH, DELETE +
+
+Value type +: +
+[{binary() | {Type, SubType, Params}, ProvideResource}] +
+
+Default value +: +
+`[ +
+

+ + + +

+ +

+ + +

+ Cowboy + 2.0 + Function Reference + +

+ +

User Guide
Function Reference

+ +

Navigation

+ +

Version select

+ +