Update Hugo, docs

1 files changed, 211 insertions, 208 deletions

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 1a288856..32c8a129 100644
--- a/docs/en/cowboy/2.0/guide/resource_design/index.html
+++ b/docs/en/cowboy/2.0/guide/resource_design/index.html
@@ -7,7 +7,7 @@
     <meta name="description" content="">
     <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara">
 
-    <meta name="generator" content="Hugo 0.17" />
+    <meta name="generator" content="Hugo 0.26" />
 
     <title>Nine Nines: Designing a resource handler</title>
 
@@ -67,219 +67,222 @@
 
 <h1 class="lined-header"><span>Designing a resource handler</span></h1>
 
-<div class="paragraph"><p>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.</p></div>

-<div class="sect1">

-<h2 id="_the_service">The service</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>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

-<code>service_available</code> callback.</p></div>

-<div class="paragraph"><p>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 <code>known_methods</code> callback.</p></div>

-</div>

-</div>

-<div class="sect1">

-<h2 id="_type_of_resource_handler">Type of resource handler</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>Am I writing a handler for a collection of resources,

-or for a single resource?</p></div>

-<div class="paragraph"><p>The semantics for each of these are quite different.

-You should not mix collection and single resource in

-the same handler.</p></div>

-</div>

-</div>

-<div class="sect1">

-<h2 id="_collection_handler">Collection handler</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>Skip this section if you are not doing a collection.</p></div>

-<div class="paragraph"><p>Is the collection hardcoded or dynamic? For example,

-if you use the route <code>/users</code> for the collection of

-users then the collection is hardcoded; if you use

-<code>/forums/:category</code> for the collection of threads

-then it isn&#8217;t. When the collection is hardcoded you

-can safely assume the resource always exists.</p></div>

-<div class="paragraph"><p>What methods should I implement?</p></div>

-<div class="paragraph"><p>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.</p></div>

-<div class="paragraph"><p>HEAD and GET are used to retrieve the collection.

-If you allow GET, also allow HEAD as there&#8217;s no extra

-work required to make it work.</p></div>

-<div class="paragraph"><p>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.</p></div>

-<div class="paragraph"><p>The next methods are more rarely allowed.</p></div>

-<div class="paragraph"><p>PUT is used to create a new collection (when

-the collection isn&#8217;t hardcoded), or replace

-the entire collection.</p></div>

-<div class="paragraph"><p>DELETE is used to delete the entire collection.</p></div>

-<div class="paragraph"><p>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.</p></div>

-</div>

-</div>

-<div class="sect1">

-<h2 id="_single_resource_handler">Single resource handler</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>Skip this section if you are doing a collection.</p></div>

-<div class="paragraph"><p>What methods should I implement?</p></div>

-<div class="paragraph"><p>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.</p></div>

-<div class="paragraph"><p>HEAD and GET are used to retrieve the resource.

-If you allow GET, also allow HEAD as there&#8217;s no extra

-work required to make it work.</p></div>

-<div class="paragraph"><p>POST is used to update the resource.</p></div>

-<div class="paragraph"><p>PUT is used to create a new resource (when it doesn&#8217;t

-already exist) or replace the resource.</p></div>

-<div class="paragraph"><p>DELETE is used to delete the resource.</p></div>

-<div class="paragraph"><p>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.</p></div>

-</div>

-</div>

-<div class="sect1">

-<h2 id="_the_resource">The resource</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>Following the above discussion, implement the

-<code>allowed_methods</code> callback.</p></div>

-<div class="paragraph"><p>Does the resource always exist? If it may not, implement

-the <code>resource_exists</code> callback.</p></div>

-<div class="paragraph"><p>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 <code>is_authorized</code> callback.</p></div>

-<div class="paragraph"><p>Do I need fine-grained access control? How do I determine

-that they are authorized access? Handle that in your

-<code>is_authorized</code> callback.</p></div>

-<div class="paragraph"><p>Can access to a resource be forbidden regardless of access

-being authorized? A simple example of that is censorship

-of a resource. Implement the <code>forbidden</code> callback.</p></div>

-<div class="paragraph"><p>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 <code>uri_too_long</code>.</p></div>

-</div>

-</div>

-<div class="sect1">

-<h2 id="_representations">Representations</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>What media types do I provide? If text based, what charsets

-are provided? What languages do I provide?</p></div>

-<div class="paragraph"><p>Implement the mandatory <code>content_types_provided</code>. Prefix

-the callbacks with <code>to_</code> for clarity. For example, <code>to_html</code>

-or <code>to_text</code>.</p></div>

-<div class="paragraph"><p>Implement the <code>languages_provided</code> or <code>charsets_provided</code>

-callbacks if applicable.</p></div>

-<div class="paragraph"><p>Is there any other header that may make the representation

-of the resource vary? Implement the <code>variances</code> callback.</p></div>

-<div class="paragraph"><p>Depending on your choices for caching content, you may

-want to implement one or more of the <code>generate_etag</code>,

-<code>last_modified</code> and <code>expires</code> callbacks.</p></div>

-<div class="paragraph"><p>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 <code>multiple_choices</code> callback.</p></div>

-</div>

-</div>

-<div class="sect1">

-<h2 id="_redirections">Redirections</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>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 <code>previously_existed</code> callback.</p></div>

-<div class="paragraph"><p>Was the resource moved, and is the move temporary? If

-it is explicitly temporary, for example due to maintenance,

-implement the <code>moved_temporarily</code> callback. Otherwise,

-implement the <code>moved_permanently</code> callback.</p></div>

-</div>

-</div>

-<div class="sect1">

-<h2 id="_the_request">The request</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>Do you need to read the query string? Individual headers?

-Implement <code>malformed_request</code> and do all the parsing and

-validation in this function. Note that the body should not

-be read at this point.</p></div>

-<div class="paragraph"><p>May there be a request body? Will I know its size?

-What&#8217;s the maximum size of the request body I&#8217;m willing

-to accept? Implement <code>valid_entity_length</code>.</p></div>

-<div class="paragraph"><p>Finally, take a look at the sections corresponding to the

-methods you are implementing.</p></div>

-</div>

-</div>

-<div class="sect1">

-<h2 id="_options_method">OPTIONS method</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>Cowboy by default will send back a list of allowed methods.

-Do I need to add more information to the response? Implement

-the <code>options</code> method.</p></div>

-</div>

-</div>

-<div class="sect1">

-<h2 id="_get_and_head_methods">GET and HEAD methods</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>If you implement the methods GET and/or HEAD, you must

-implement one <code>ProvideResource</code> callback for each

-content-type returned by the <code>content_types_provided</code>

-callback.</p></div>

-</div>

-</div>

-<div class="sect1">

-<h2 id="_put_post_and_patch_methods">PUT, POST and PATCH methods</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>If you implement the methods PUT, POST and/or PATCH,

-you must implement the <code>content_types_accepted</code> callback,

-and one <code>AcceptResource</code> callback for each content-type

-it returns. Prefix the <code>AcceptResource</code> callback names

-with <code>from_</code> for clarity. For example, <code>from_html</code> or

-<code>from_json</code>.</p></div>

-<div class="paragraph"><p>Do we want to allow the POST method to create individual

-resources directly through their URI (like PUT)? Implement

-the <code>allow_missing_post</code> callback. It is recommended to

-explicitly use PUT in these cases instead.</p></div>

-<div class="paragraph"><p>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

-<code>is_conflict</code> callback.</p></div>

-</div>

-</div>

-<div class="sect1">

-<h2 id="_delete_methods">DELETE methods</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>If you implement the method DELETE, you must implement

-the <code>delete_resource</code> callback.</p></div>

-<div class="paragraph"><p>When <code>delete_resource</code> 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

-<code>delete_completed</code> callback.</p></div>

-</div>

-</div>

+<div class="paragraph"><p>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.</p></div>
+<div class="sect1">
+<h2 id="_the_service">The service</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>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
+<code>service_available</code> callback.</p></div>
+<div class="paragraph"><p>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 <code>known_methods</code> callback.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_type_of_resource_handler">Type of resource handler</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Am I writing a handler for a collection of resources,
+or for a single resource?</p></div>
+<div class="paragraph"><p>The semantics for each of these are quite different.
+You should not mix collection and single resource in
+the same handler.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_collection_handler">Collection handler</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Skip this section if you are not doing a collection.</p></div>
+<div class="paragraph"><p>Is the collection hardcoded or dynamic? For example,
+if you use the route <code>/users</code> for the collection of
+users then the collection is hardcoded; if you use
+<code>/forums/:category</code> for the collection of threads
+then it isn&#8217;t. When the collection is hardcoded you
+can safely assume the resource always exists.</p></div>
+<div class="paragraph"><p>What methods should I implement?</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>HEAD and GET are used to retrieve the collection.
+If you allow GET, also allow HEAD as there&#8217;s no extra
+work required to make it work.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>The next methods are more rarely allowed.</p></div>
+<div class="paragraph"><p>PUT is used to create a new collection (when
+the collection isn&#8217;t hardcoded), or replace
+the entire collection.</p></div>
+<div class="paragraph"><p>DELETE is used to delete the entire collection.</p></div>
+<div class="paragraph"><p>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.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_single_resource_handler">Single resource handler</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Skip this section if you are doing a collection.</p></div>
+<div class="paragraph"><p>What methods should I implement?</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>HEAD and GET are used to retrieve the resource.
+If you allow GET, also allow HEAD as there&#8217;s no extra
+work required to make it work.</p></div>
+<div class="paragraph"><p>POST is used to update the resource.</p></div>
+<div class="paragraph"><p>PUT is used to create a new resource (when it doesn&#8217;t
+already exist) or replace the resource.</p></div>
+<div class="paragraph"><p>DELETE is used to delete the resource.</p></div>
+<div class="paragraph"><p>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.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_the_resource">The resource</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Following the above discussion, implement the
+<code>allowed_methods</code> callback.</p></div>
+<div class="paragraph"><p>Does the resource always exist? If it may not, implement
+the <code>resource_exists</code> callback.</p></div>
+<div class="paragraph"><p>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 <code>is_authorized</code> callback.</p></div>
+<div class="paragraph"><p>Do I need fine-grained access control? How do I determine
+that they are authorized access? Handle that in your
+<code>is_authorized</code> callback.</p></div>
+<div class="paragraph"><p>Can access to a resource be forbidden regardless of access
+being authorized? A simple example of that is censorship
+of a resource. Implement the <code>forbidden</code> callback.</p></div>
+<div class="paragraph"><p>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 <code>uri_too_long</code>.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_representations">Representations</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>What media types do I provide? If text based, what charsets
+are provided? What languages do I provide?</p></div>
+<div class="paragraph"><p>Implement the mandatory <code>content_types_provided</code>. Prefix
+the callbacks with <code>to_</code> for clarity. For example, <code>to_html</code>
+or <code>to_text</code>.</p></div>
+<div class="paragraph"><p>Implement the <code>languages_provided</code> or <code>charsets_provided</code>
+callbacks if applicable.</p></div>
+<div class="paragraph"><p>Is there any other header that may make the representation
+of the resource vary? Implement the <code>variances</code> callback.</p></div>
+<div class="paragraph"><p>Depending on your choices for caching content, you may
+want to implement one or more of the <code>generate_etag</code>,
+<code>last_modified</code> and <code>expires</code> callbacks.</p></div>
+<div class="paragraph"><p>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 <code>multiple_choices</code> callback.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_redirections">Redirections</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>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 <code>previously_existed</code> callback.</p></div>
+<div class="paragraph"><p>Was the resource moved, and is the move temporary? If
+it is explicitly temporary, for example due to maintenance,
+implement the <code>moved_temporarily</code> callback. Otherwise,
+implement the <code>moved_permanently</code> callback.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_the_request">The request</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Do you need to read the query string? Individual headers?
+Implement <code>malformed_request</code> and do all the parsing and
+validation in this function. Note that the body should not
+be read at this point.</p></div>
+<div class="paragraph"><p>May there be a request body? Will I know its size?
+What&#8217;s the maximum size of the request body I&#8217;m willing
+to accept? Implement <code>valid_entity_length</code>.</p></div>
+<div class="paragraph"><p>Finally, take a look at the sections corresponding to the
+methods you are implementing.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_options_method">OPTIONS method</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Cowboy by default will send back a list of allowed methods.
+Do I need to add more information to the response? Implement
+the <code>options</code> method.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_get_and_head_methods">GET and HEAD methods</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>If you implement the methods GET and/or HEAD, you must
+implement one <code>ProvideResource</code> callback for each
+content-type returned by the <code>content_types_provided</code>
+callback.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_put_post_and_patch_methods">PUT, POST and PATCH methods</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>If you implement the methods PUT, POST and/or PATCH,
+you must implement the <code>content_types_accepted</code> callback,
+and one <code>AcceptResource</code> callback for each content-type
+it returns. Prefix the <code>AcceptResource</code> callback names
+with <code>from_</code> for clarity. For example, <code>from_html</code> or
+<code>from_json</code>.</p></div>
+<div class="paragraph"><p>Do we want to allow the POST method to create individual
+resources directly through their URI (like PUT)? Implement
+the <code>allow_missing_post</code> callback. It is recommended to
+explicitly use PUT in these cases instead.</p></div>
+<div class="paragraph"><p>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
+<code>is_conflict</code> callback.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_delete_methods">DELETE methods</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>If you implement the method DELETE, you must implement
+the <code>delete_resource</code> callback.</p></div>
+<div class="paragraph"><p>When <code>delete_resource</code> 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
+<code>delete_completed</code> callback.</p></div>
+</div>
+</div>
 
 
 
 	
 		
 		
+		
+		
+		
 
 		<nav style="margin:1em 0">