Methods

If you are used to REST interfaces, the choice of HTTP methods (verbs) should be natural. The important thing to note is that the API makes use of the PATCH method [RFC5789].

For those who are new to REST, or are interested in the specific details of this API, here's a short summary.

Safe methods: GET, HEAD, OPTIONS

These methods are considered safe, in the sense that they have no other effects than sending information from the server to the client. None of them make use of a request body (although there may be query string parameters in the URI).

GET will, on success, return 200 OK and a representation of the requested resource.

HEAD is the same as GET but will only return the HTTP headers, no actual data.

OPTIONS will return 204 No Content, but include the Allow header telling the client which methods are allowed for this particular resource.

Creating resources: POST and PUT

Creating a new resource is generally achieved by posting a representation of it to an existing collection (a collection is any resource referenced by a plural noun).

Some properties of a resource are "required" (see the resource specifications). If such a property is missing from the representation, POST will fail. If an "optional" property is missing, it will be initialized with a default value.

On success, POST returns 201 Created and a representation of the created resource.

It is also possible to create several resources in one request.

If the URI of the new resource is predetermined (for example, it has been given by a URI template in a link from another resource), it does not have to be posted to a collection: you can just use PUT instead.

Updating resources: PUT and PATCH

PUT is used to completely replace whatever is currently found at a given URI with an enclosed resource representation. PATCH performs a partial update of an existing resource, which is generally more useful. (It is possible, however, for a resource to accept PUT but not PATCH.)

On success, both methods return 200 OK (or 201 Created) and a representation of the updated resource. Some key differences between the methods:

• If a "required" property is omitted, PUT will fail (just as POST would), while PATCH will leave the property unaltered.
• If an "optional" property is omitted, PUT will reset it to its default value, while PATCH will leave it unaltered (it is possible to explicitly reset a property to its default value with PATCH by setting it to null).
• PUT will remove all embedded resources from the resource, while PATCH will leave them intact, or update them through the _witheach syntax (see batch updating).

If an "immutable" property is included, both methods will fail. If a property is both "required" and "immutable", the resource will never allow PUT.

While PUT and PATCH are not safe, they are idempotent as defined by the RFC. (PATCH is not required by its defining RFC to be idempotent, so don't expect it to be in other APIs.)

Deleting resources: DELETE

The DELETE method deletes the requested resource. It returns 204 No Content on success.

DELETE is an idempotent method.