diff options
Diffstat (limited to 'docs/en/cowboy/2.0/manual/cowboy_rest')
| -rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_rest/index.html | 845 |
1 files changed, 843 insertions, 2 deletions
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 7369592c..9d46ab96 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_rest/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_rest/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.15" /> + <meta name="generator" content="Hugo 0.16" /> <title>Nine Nines: cowboy_rest(3)</title> @@ -428,10 +428,851 @@ Default value </dt>
<dd>
<p>
-`[
+<code>[{{ <<"text">>, <<"html">>, '*'}, to_html}]</code>
</p>
</dd>
</dl></div>
+<div class="paragraph"><p>With types:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Type = SubType = binary()
+</p>
+</li>
+<li>
+<p>
+Params = <em>*</em> | [{binary(), binary()}]
+</p>
+</li>
+<li>
+<p>
+ProvideResource = atom()
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>Return the list of content-types the resource provides.</p></div>
+<div class="paragraph"><p>The list must be ordered in order of preference.</p></div>
+<div class="paragraph"><p>Each content-type can be given either as a binary string or as
+a tuple containing the type, subtype and parameters.</p></div>
+<div class="paragraph"><p>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 <code>'*'</code>. If the parameters value is set to <code>[]</code>
+only content-type values with no parameters will be accepted. All
+parameter values are treated in a case sensitive manner except the
+<code>charset</code> parameter, if present, which is case insensitive.</p></div>
+<div class="paragraph"><p>The <code>ProvideResource</code> 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.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+GET, HEAD
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+iodata() | {stream, Fun} | {stream, Len, Fun} | {chunked, ChunkedFun}
+</p>
+</dd>
+<dt class="hdlist1">
+Default behavior
+</dt>
+<dd>
+<p>
+Crash if undefined.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the response body.</p></div>
+<div class="paragraph"><p>The response body may be provided directly or through a fun.
+If a fun tuple is returned, the appropriate <code>set_resp_body_fun</code>
+function will be called. Please refer to the documentation for
+these functions for more information about the types.</p></div>
+<div class="paragraph"><p>The call to this callback happens a good time after the call to
+<code>content_types_provided/2</code>, when it is time to start rendering
+the response body.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_delete_completed">delete_completed</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+DELETE
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+boolean()
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+true
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return whether the delete action has been completed.</p></div>
+<div class="paragraph"><p>This function should return <code>false</code> if there is no guarantee
+that the resource gets deleted immediately from the system,
+including from any internal cache.</p></div>
+<div class="paragraph"><p>When this function returns <code>false</code>, a <code>202 Accepted</code>
+response will be sent instead of a <code>200 OK</code> or <code>204 No Content</code>.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_delete_resource">delete_resource</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+DELETE
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+boolean()
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+false
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Delete the resource.</p></div>
+<div class="paragraph"><p>The value returned indicates if the action was successful,
+regardless of whether the resource is immediately deleted
+from the system.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_expires">expires</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+GET, HEAD
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+calendar:datetime() | binary() | undefined
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+undefined
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the date of expiration of the resource.</p></div>
+<div class="paragraph"><p>This date will be sent as the value of the expires header.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_forbidden">forbidden</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+all
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+boolean()
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+false
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return whether access to the resource is forbidden.</p></div>
+<div class="paragraph"><p>A <code>403 Forbidden</code> response will be sent if this
+function returns <code>true</code>. This status code means that
+access is forbidden regardless of authentication,
+and that the request shouldn’t be repeated.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_generate_etag">generate_etag</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+GET, HEAD, POST, PUT, PATCH, DELETE
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+binary() | {weak | strong, binary()}
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+undefined
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the entity tag of the resource.</p></div>
+<div class="paragraph"><p>This value will be sent as the value of the etag header.</p></div>
+<div class="paragraph"><p>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.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_is_authorized">is_authorized</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+all
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+true | {false, AuthHeader}
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+true
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>With types:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+AuthHead = iodata()
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>Return whether the user is authorized to perform the action.</p></div>
+<div class="paragraph"><p>This function should be used to perform any necessary
+authentication of the user before attempting to perform
+any action on the resource.</p></div>
+<div class="paragraph"><p>If the authentication fails, the value returned will be sent
+as the value for the www-authenticate header in the
+<code>401 Unauthorized</code> response.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_is_conflict">is_conflict</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+PUT
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+boolean()
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+false
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return whether the put action results in a conflict.</p></div>
+<div class="paragraph"><p>A <code>409 Conflict</code> response will be sent if this function
+returns <code>true</code>.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_known_methods">known_methods</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+all
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+[binary()]
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+<code>[<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]</code>
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the list of known methods.</p></div>
+<div class="paragraph"><p>The full list of methods known by the server should be
+returned, regardless of their use in the resource.</p></div>
+<div class="paragraph"><p>The default value lists the methods Cowboy knows and
+implement in <code>cowboy_rest</code>.</p></div>
+<div class="paragraph"><p>Methods are case sensitive. Standard methods are always uppercase.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_languages_provided">languages_provided</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+GET, HEAD, POST, PUT, PATCH, DELETE
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+[binary()]
+</p>
+</dd>
+<dt class="hdlist1">
+Default behavior
+</dt>
+<dd>
+<p>
+Skip to the next step if undefined.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the list of languages the resource provides.</p></div>
+<div class="paragraph"><p>The list must be ordered in order of preference.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>The chosen language will be set in the <code>Req</code> object as the meta
+value <code>language</code>.</p></div>
+<div class="paragraph"><p>While languages are case insensitive, this callback is expected
+to return them as lowercase binary.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_last_modified">last_modified</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+GET, HEAD, POST, PUT, PATCH, DELETE
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+calendar:datetime()
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+undefined
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the date of last modification of the resource.</p></div>
+<div class="paragraph"><p>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.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_malformed_request">malformed_request</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+all
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+boolean()
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+false
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return whether the request is malformed.</p></div>
+<div class="paragraph"><p>Cowboy has already performed all the necessary checks
+by the time this function is called, so few resources
+are expected to implement it.</p></div>
+<div class="paragraph"><p>The check is to be done on the request itself, not on
+the request body, which is processed later.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_moved_permanently">moved_permanently</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+GET, HEAD, POST, PUT, PATCH, DELETE
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+{true, URL} | false
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+false
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>With types:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+URL = iodata()
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>Return whether the resource was permanently moved.</p></div>
+<div class="paragraph"><p>If it was, its new URL is also returned and sent in the
+location header in the response.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_moved_temporarily">moved_temporarily</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+GET, HEAD, POST, PATCH, DELETE
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+{true, URL} | false
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+false
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>With types:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+URL = iodata()
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>Return whether the resource was temporarily moved.</p></div>
+<div class="paragraph"><p>If it was, its new URL is also returned and sent in the
+location header in the response.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_multiple_choices">multiple_choices</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+GET, HEAD, POST, PUT, PATCH, DELETE
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+boolean()
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+false
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return whether there are multiple representations of the resource.</p></div>
+<div class="paragraph"><p>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 <code>true</code>,
+the response body should include information about these
+different representations using <code>cowboy_req:set_resp_body/2</code>.
+The content-type of the response should be the one previously
+negociated and that can be obtained by calling
+<code>cowboy_req:meta(media_type, Req)</code>.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_options">options</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+OPTIONS
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+ok
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+ok
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Handle a request for information.</p></div>
+<div class="paragraph"><p>The response should inform the client the communication
+options available for this resource.</p></div>
+<div class="paragraph"><p>By default, Cowboy will send a <code>200 OK</code> response with the
+allow header set.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_previously_existed">previously_existed</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+GET, HEAD, POST, PATCH, DELETE
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+boolean()
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+false
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return whether the resource existed previously.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_resource_exists">resource_exists</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+GET, HEAD, POST, PUT, PATCH, DELETE
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+boolean()
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+true
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return whether the resource exists.</p></div>
+<div class="paragraph"><p>If it exists, conditional headers will be tested before
+attempting to perform the action. Otherwise, Cowboy will
+check if the resource previously existed first.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_service_available">service_available</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+all
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+boolean()
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+true
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return whether the service is available.</p></div>
+<div class="paragraph"><p>This function can be used to test that all relevant backend
+systems are up and able to handle requests.</p></div>
+<div class="paragraph"><p>A <code>503 Service Unavailable</code> response will be sent if this
+function returns <code>false</code>.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_uri_too_long">uri_too_long</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+all
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+boolean()
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+false
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return whether the requested URI is too long.</p></div>
+<div class="paragraph"><p>Cowboy has already performed all the necessary checks
+by the time this function is called, so few resources
+are expected to implement it.</p></div>
+<div class="paragraph"><p>A <code>414 Request-URI Too Long</code> response will be sent if this
+function returns <code>true</code>.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_valid_content_headers">valid_content_headers</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+all
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+boolean()
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+true
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return whether the content-* headers are valid.</p></div>
+<div class="paragraph"><p>This also applies to the transfer-encoding header. This
+function must return <code>false</code> for any unknown content-*
+headers, or if the headers can’t be understood. The
+function <code>cowboy_req:parse_header/2</code> can be used to
+quickly check the headers can be parsed.</p></div>
+<div class="paragraph"><p>A <code>501 Not Implemented</code> response will be sent if this
+function returns <code>false</code>.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_valid_entity_length">valid_entity_length</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+all
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+boolean()
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+true
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return whether the request body length is within acceptable boundaries.</p></div>
+<div class="paragraph"><p>A <code>413 Request Entity Too Large</code> response will be sent if this
+function returns <code>false</code>.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_variances">variances</h3>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+Methods
+</dt>
+<dd>
+<p>
+GET, HEAD, POST, PUT, PATCH, DELETE
+</p>
+</dd>
+<dt class="hdlist1">
+Value type
+</dt>
+<dd>
+<p>
+[binary()]
+</p>
+</dd>
+<dt class="hdlist1">
+Default value
+</dt>
+<dd>
+<p>
+[]
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p>Return the list of headers that affect the representation of the resource.</p></div>
+<div class="paragraph"><p>These request headers return the same resource but with different
+parameters, like another language or a different content-type.</p></div>
+<div class="paragraph"><p>Cowboy will automatically add the accept, accept-language and
+accept-charset headers to the list if the respective functions
+were defined in the resource.</p></div>
+<div class="paragraph"><p>This operation is performed right before the <code>resource_exists/2</code>
+callback. All responses past that point will contain the vary
+header which holds this list.</p></div>
</div>
</div>
</div>
|