Documentation
API Conventions
How the API handles redirects, which HTTP methods it uses and how to send timestamps.
These rules apply to every endpoint of API v3 and v4. Read them before you write a client.
HTTP redirects
API v3 and v4 use HTTP redirects where needed. Any request can return a redirect. A redirect is
not an error, and the client must follow it. The Location header of a redirect response holds
the URI where the client must repeat the request.
| Status code | Meaning |
|---|---|
| 301 | Permanent redirect. The resource has moved to the URL in the Location header for good. |
| 302 | Temporary redirect. The resource is at the URL in the Location header for now. |
The API can also use other redirect status codes from the HTTP 1.1 specification.
HTTP methods
API v3 uses the HTTP method that matches each action, where possible.
| Method | Use |
|---|---|
| GET | Read one resource or a list of resources. |
| POST | Create a resource. |
| PATCH | Update a resource with partial JSON data. For example, a Diamond resource has the color and clarity attributes. A PATCH request can send one or more of these attributes. |
| PUT | Works the same as PATCH. Fields you leave out stay unchanged. |
| DELETE | Delete a resource. |
Timestamps
Send every timestamp in ISO 8601 format with the timezone, for example 2014-02-27T15:05:06+01:00.
When an API call accepts a timestamp, the API uses that exact value.