REST API Request Methods

The common HTTP/1.1 methods are listed below

GET

  • A REST API client uses the GET method in a request message to retrieve the state of a resource, in some representational form.
  • A client’s GET request message may contain headers but no body
  • The architecture of the Web relies heavily on the nature of the GET method. Clients count on being able to repeat GET requests without causing side effects. Caches depend on the ability to serve cached representations without contacting the origin server.

PUT

  • Must be used to both insert and update a stored resource
  • PUT must be used to add a new resource to a store, with a URI specified by the client.
  • The PUT request message may include a body that reflects the desired changes.
  • PUT must be used to update mutable resources
  • If a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response. If an existing resource is modified,either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.

https://www.rfc-editor.org/rfc/rfc2616#section-9.6

POST

  • POST must be used to create a new resource in a collection
  • The action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either 200 (OK) or 204 (No Content) is the appropriate response status

https://www.rfc-editor.org/rfc/rfc2616#section-9.5

DELETE

  • DELETE must be used to remove a resource from its parent
  • A client uses DELETE to request that a resource be completely removed from its parent, which is often a collection or store.
  • Once a DELETE request has been processed for a given resource, the resource can no longer be found by clients.
  • Therefore, any future attempt to retrieve the resource’s state representation, using either GET or HEAD, must result in a 404 (“Not Found”) status returned by the API
  • A successful response SHOULD be 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has not yet been enacted, or 204 (No Content) if the action has been enacted but the response does not include an entity.
  • Responses to this method are not cacheable.

OPTIONS

  • OPTIONS should be used to retrieve metadata that describes a resource’s available interactions
  • Clients may use the OPTIONS request method to retrieve resource metadata that includes an Allow header value.

HEAD

  • Clients use HEAD to retrieve the headers without a body.
  • HEAD returns the same response as GET, except that the API returns an empty body. Clients can use this method to check whether a resource exists or to read its metadata

OPTIONS VS HEAD

OPTIONS method returns info about API (methods/content type)

HEAD method returns info about resource (version/length/type)