cowboy/doc/src/guide/resource_design.asciidoc

[[resource_design]]
== Designing a resource handler

This chapter aims to provide you with a list of questions
you must answer in order to write a good resource handler.
It is meant to be usable as a step by step guide.

=== The service

Can the service become unavailable, and when it does, can
we detect it? For example, database connectivity problems
may be detected early. We may also have planned outages
of all or parts of the system. Implement the
`service_available` callback.

What HTTP methods does the service implement? Do we need
more than the standard OPTIONS, HEAD, GET, PUT, POST,
PATCH and DELETE? Are we not using one of those at all?
Implement the `known_methods` callback.

=== Type of resource handler

Am I writing a handler for a collection of resources,
or for a single resource?

The semantics for each of these are quite different.
You should not mix collection and single resource in
the same handler.

=== Collection handler

Skip this section if you are not doing a collection.

Is the collection hardcoded or dynamic? For example,
if you use the route `/users` for the collection of
users then the collection is hardcoded; if you use
`/forums/:category` for the collection of threads
then it isn't. When the collection is hardcoded you
can safely assume the resource always exists.

What methods should I implement?

OPTIONS is used to get some information about the
collection. It is recommended to allow it even if you
do not implement it, as Cowboy has a default
implementation built-in.

HEAD and GET are used to retrieve the collection.
If you allow GET, also allow HEAD as there's no extra
work required to make it work.

POST is used to create a new resource inside the
collection. Creating a resource by using POST on
the collection is useful when resources may be
created before knowing their URI, usually because
parts of it are generated dynamically. A common
case is some kind of auto incremented integer
identifier.

The next methods are more rarely allowed.

PUT is used to create a new collection (when
the collection isn't hardcoded), or replace
the entire collection.

DELETE is used to delete the entire collection.

PATCH is used to modify the collection using
instructions given in the request body. A PATCH
operation is atomic. The PATCH operation may
be used for such things as reordering; adding,
modifying or deleting parts of the collection.

=== Single resource handler

Skip this section if you are doing a collection.

What methods should I implement?

OPTIONS is used to get some information about the
resource. It is recommended to allow it even if you
do not implement it, as Cowboy has a default
implementation built-in.

HEAD and GET are used to retrieve the resource.
If you allow GET, also allow HEAD as there's no extra
work required to make it work.

POST is used to update the resource.

PUT is used to create a new resource (when it doesn't
already exist) or replace the resource.

DELETE is used to delete the resource.

PATCH is used to modify the resource using
instructions given in the request body. A PATCH
operation is atomic. The PATCH operation may
be used for adding, removing or modifying specific
values in the resource.

=== The resource

Following the above discussion, implement the
`allowed_methods` callback.

Does the resource always exist? If it may not, implement
the `resource_exists` callback.

Do I need to authenticate the client before they can
access the resource? What authentication mechanisms
should I provide? This may include form-based, token-based
(in the URL or a cookie), HTTP basic, HTTP digest,
SSL certificate or any other form of authentication.
Implement the `is_authorized` callback.

Do I need fine-grained access control? How do I determine
that they are authorized access? Handle that in your
`is_authorized` callback.

Can access to a resource be forbidden regardless of access
being authorized? A simple example of that is censorship
of a resource. Implement the `forbidden` callback.

Are there any constraints on the length of the resource URI?
For example, the URI may be used as a key in storage and may
have a limit in length. Implement `uri_too_long`.

=== Representations

What media types do I provide? If text based, what charsets
are provided? What languages do I provide?

Implement the mandatory `content_types_provided`. Prefix
the callbacks with `to_` for clarity. For example, `to_html`
or `to_text`.

Implement the `languages_provided` or `charsets_provided`
callbacks if applicable.

Is there any other header that may make the representation
of the resource vary? Implement the `variances` callback.

Depending on your choices for caching content, you may
want to implement one or more of the `generate_etag`,
`last_modified` and `expires` callbacks.

Do I want the user or user agent to actively choose a
representation available? Send a list of available
representations in the response body and implement
the `multiple_choices` callback.

=== Redirections

Do I need to keep track of what resources were deleted?
For example, you may have a mechanism where moving a
resource leaves a redirect link to its new location.
Implement the `previously_existed` callback.

Was the resource moved, and is the move temporary? If
it is explicitly temporary, for example due to maintenance,
implement the `moved_temporarily` callback. Otherwise,
implement the `moved_permanently` callback.

=== The 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`.

Finally, take a look at the sections corresponding to the
methods you are implementing.

=== OPTIONS method

Cowboy by default will send back a list of allowed methods.
Do I need to add more information to the response? Implement
the `options` method.

=== GET and HEAD methods

If you implement the methods GET and/or HEAD, you must
implement one `ProvideResource` callback for each
content-type returned by the `content_types_provided`
callback.

=== PUT, POST and PATCH methods

If you implement the methods PUT, POST and/or PATCH,
you must implement the `content_types_accepted` callback,
and one `AcceptResource` callback for each content-type
it returns. Prefix the `AcceptResource` callback names
with `from_` for clarity. For example, `from_html` or
`from_json`.

Do we want to allow the POST method to create individual
resources directly through their URI (like PUT)? Implement
the `allow_missing_post` callback. It is recommended to
explicitly use PUT in these cases instead.

May there be conflicts when using PUT to create or replace
a resource? Do we want to make sure that two updates around
the same time are not cancelling one another? Implement the
`is_conflict` callback.

=== DELETE methods

If you implement the method DELETE, you must implement
the `delete_resource` callback.

When `delete_resource` returns, is the resource completely
removed from the server, including from any caching service?
If not, and/or if the deletion is asynchronous and we have
no way of knowing it has been completed yet, implement the
`delete_completed` callback.