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.

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