HTTP Methods

The primary or most-commonly-used HTTP verbs (or methods, as they are properly called) are POST, GET, PUT, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. There are a number of other verbs, too, but are utilized less frequently.

Below is a table summarizing the methods used by this service API.


HTTP VERB

CRUD

DESCRIPTION

POST

CREATE

Used to create new resources

NOT SAFE - NOT IDEMPOTENT

Making two identical POST will duplicate the resource

GET

READ

Retrieve a representation of a resource

SAFE - IDEMPOTENT

Multiple identical requests return the same result

PUT

UPDATE

Update or Create a resource

NOT SAFE - IDEMPOTENT

Multiple identical requests will update the same resource

DELETE

DELETE

Used to delete a resource

NOT SAFE - IDEMPOTENT §

Multiple identical requests will delete same resource



§

Calling DELETE on a resource a second time will often return a 404 (NOT FOUND) since it was already removed and therefore is no longer findable. This, by some opinions, makes DELETE operations no longer idempotent, however, the end-state of the resource is the same. Returning a 404 is acceptable and communicates accurately the status of the call.


IDEMPOTENCE

Clients can make that same call repeatedly while producing the same result.

In other words, making multiple identical requests has the same effect as making a single request. Note that while idempotent operations produce the same result on the server (no side effects), the response itself may not be the same (e.g. a resource's state may change between requests).