resources.md

layout	title
default	Webmachine resource functions

Webmachine resource functions

All webmachine resources should include the webmachine resource library:

{% highlight erlang %} -include_lib("webmachine/include/webmachine.hrl"). {% endhighlight %}

All webmachine resources should define and export init/1, which will receive a configuration property list from the dispatcher as its argument. This function should, if successful, return {ok, Context}. Context is any term, and will be threaded through all of the other webmachine resource functions. Alternately, the resource can go into debugging mode by returning {% raw %}{{trace, Dir}{% endraw %} , Context} instead -- see the tracing documentation for more information.

All webmachine resource functions are of the signature:

{% highlight erlang %} f(ReqData, Context) -> {Result, ReqData, Context} {% endhighlight %}

Context is an arbitrary term() that is specific to your application. Webmachine will never do anything with this term other than threading it through the various functions of your resource. This is the means by which transient application-specific request state is passed along between functions.

ReqData is a #wm_reqdata{} term, and is manipulated via the wrq interface. A resource function may access request data (such as header values) from the input value. If a resource function wishes to affect the response data in some way other than that implied by its return value (e.g. adding an X-Header) then it should modify the returned ReqData term accordingly.

The rest of this document is about the effects produced by different values in the Result term.

There are over 30 resource functions you can define, but any of them can be omitted as they have reasonable defaults.

Each function is described below, showing the default and allowed values that may be in the Result term. The default will be used if a resource does not export the function. If a function has an "X" in the "Halt" column, it also has the option of returning either of the two following special values for Result:

Result	Effect
{error, Err::term()}	Immediately end processing of this request, returning a 500 response code. The response body will contain the Err term.
{halt, Code::integer()}	Immediately end processing of this request, returning response code Code. It is the responsibility of the resource to ensure that all necessary response header and body elements are filled in ReqData in order to make that reponse code valid.
{halt, {Code::integer(), ReasonPhrase::iolist()}}	Same as {halt, Code::integer()} but supply a custom reason phrase for the HTTP status code as well.

Any function which has no description is optional and the effect of its return value should be evident from examining the diagram.

Function	Halt	Default	Allowed	Description
resource_exists	true	X	`true	false`
service_available	true	X	`true	false`
is_authorized	true	X	`true	AuthHead`
forbidden	false	X	`true	false`
allow_missing_post	false	X	`true	false`
malformed_request	false	X	`true	false`
uri_too_long	false	X	`true	false`
known_content_type	true	X	`true	false`
valid_content_headers	true	X	`true	false`
valid_entity_length	true	X	`true	false`
options	[]		[Header]	If the OPTIONS method is supported and is used, the return value of this function is expected to be a list of pairs representing header names and values that should appear in the response.
allowed_methods	['GET', 'HEAD']		[Method]	If a Method not in this list is requested, then a 405 Method Not Allowed will be sent. Note that these are all-caps and are atoms. (single-quoted)
delete_resource	false	X	`true	false`
delete_completed	true	X	`true	false`
post_is_create	false		`true	false`
create_path	undefined		Path	This will be called on a POST request if post_is_create returns true. It is an error for this function to not produce a Path if post_is_create returns true. The Path returned should be a valid URI part following the dispatcher prefix. That Path will replace the previous one in the return value of wrq:disp_path(ReqData) for all subsequent resource function calls in the course of this request.
process_post	false	X	`true	false`
content_types_provided	[{"text/html", to_html}]		[{Mediatype, Handler}]	This should return a list of pairs where each pair is of the form {Mediatype, Handler} where Mediatype is a string of content-type format and the Handler is an atom naming the function which can provide a resource representation in that media type. Content negotiation is driven by this return value. For example, if a client request includes an Accept header with a value that does not appear as a first element in any of the return tuples, then a 406 Not Acceptable will be sent.
content_types_accepted	[]		[{Mediatype, Handler}]	This is used similarly to content_types_provided, except that it is for incoming resource representations -- for example, PUT requests. Handler functions usually want to use wrq:req_body(ReqData) to access the incoming request body.
charsets_provided	no_charset		`no_charset	[{Charset, CharsetConverter}] `
encodings_provided	[{"identity", fun(X) -> X end}]		[{Encoding, Encoder}]	This must be a list of pairs where in each pair Encoding is a string naming a valid content encoding and Encoder is a callable function in the resource which will be called on the produced body in a GET and ensure that it is so encoded. One useful setting is to have the function check on method, and on GET requests return [{"identity", fun(X) -> X end}, {"gzip", fun(X) -> zlib:gzip(X) end}] as this is all that is needed to support gzip content encoding.
variances	[]		[HeaderName]	If this function is implemented, it should return a list of strings with header names that should be included in a given response's Vary header. The standard conneg headers (Accept, Accept-Encoding, Accept-Charset, Accept-Language) do not need to be specified here as Webmachine will add the correct elements of those automatically depending on resource behavior.
is_conflict	false		`true	false`
multiple_choices	false	X	`true	false`
previously_existed	false	X	`true	false`
moved_permanently	false	X	`{true, MovedURI}	false`
moved_temporarily	false	X	`{true, MovedURI}	false`
last_modified	undefined		`undefined	` {% raw %}{{YYYY,MM,DD}, {Hour,Min,Sec}}{% endraw %}``
expires	undefined		`undefined	`{% raw %}{{YYYY,MM,DD}, {Hour,Min,Sec}}{% endraw %}``
generate_etag	undefined		`undefined	ETag`
finish_request	true		`true	false`
body-producing function named as a Handler by content_types_provided		X	Body	The Body should be either an iolist() or {stream,streambody()}
POST-processing function named as a Handler by content_types_accepted		X	true

The above are all of the supported predefined resource functions. In addition to whichever of these a resource wishes to use, it also must export all of the functions named in the return values of the content_types_provided and content_types_accepted functions with behavior as described in the bottom two rows of the table.