========================================
HTTP methods, status codes, and headers
========================================

The API uses the following methods, status codes, and headers.

Methods
--------

The following HTTP methods are supported.

-  GET: retrieve a resource
-  POST: create a new resource
-  PUT: replace the resource with the one given in the request
-  PATCH: update the resource with fields provided in the request
-  DELETE: delete the resource
-  OPTIONS: list the valid methods for the resource
-  HEAD: retrieve the headers that would be returned for a GET request,
   but omit the body of the response

Some methods are not available for certain URLs. To see which methods
are available for a URI, make an OPTIONS request to the URI or refer to
the `URIs documentation <uris/index.html>`__.

Alternative method specifications
++++++++++++++++++++++++++++++++++

Some clients, including certain web browsers, can only make GET and POST
requests. To allow these clients to fake PUT/PATCH/DELETE/etc. requests,
there are two ways to specify the HTTP method of a request in a regular
POST request.

POST field
^^^^^^^^^^^

To fake a certain HTTP method in a client that doesn't support the
method, supply a ``_method`` parameter with the name of the desired
method. For example, to delete a resource from a client that doesn't
support the DELETE method, submit a request with a ``_method`` parameter
of ``DELETE``. In a web application, this could be done with the
following hidden form field:

::

    <input type="hidden" name="_method" value="DELETE">

HTTP header
^^^^^^^^^^^^

Similarly, HTTP methods can be faked with the ``X-HTTP-Method-Override``
header. For example, to fake a DELETE request with an HTTP header,
submit the request with the ``X-HTTP-Method-Override`` set to
``DELETE``.

Status codes
-------------

The following HTTP status codes are the most common ones received from
the server.

-  200 OK: The request completed successfully.
-  201 Created: A new resource has been created.
-  204 No content: The request resulted in no information that could be
   sent. This happens for successful DELETE requests.
-  400 Bad request: The request cannot be completed due to a client
   error. The response will include information about the error.
-  401 Unauthorized: The client's authentication failed.
-  403 Forbidden: The client does not have permission to perform the
   request.
-  404 Not found: No resource was found at the requested URI.
-  405 Method not allowed: The supplied method is not allowed for the
   resource.
-  415 Unsupported media type: The request had a content-type not
   supported by the server.

Headers
--------

The server accepts the following HTTP headers.

-  Accept: The content-type(s) the client is willing to receive. This
   header can be faked by appending the request URI with an ``accept``
   parameter. For example, to request JSON data when using the browsable
   HTML API, add ``?accept=application/json`` to the URI. Valid values
   are:

   -  application/json (default if no Accept header is provided)
   -  text/html (default for the browsable API)
   -  application/xml
   -  application/yaml

-  Content-Type: The content type of the request body. Valid values are:

   -  application/json
   -  application/x-www-form-urlencoded
   -  multipart/form-data

-  Authorization: the HTTP basic authorization header

The server sends the following headers:

-  Allow: A list of valid request methods for the resource
-  Content-Type: The content type of the returned resource
-  Location: The URI of the new object created by a successful POST
