HTTP Methods in REST

There are 4 basic HTTP verbs (CRUD) we use in requests to interact with resources in a REST system:

GET

Retrieve information. GET requests must be safe and idempotent, that mean regardless of how many times it repeats with the same parameters, the results are the same. They can have side effects, but the user doesn't expect them, so they cannot be critical to the operation of the system. Requests can also be partial or conditional. Use of query params allows to implement additional operation on targeting resource like filtering, sorting, pagination...

Note:

GET requests must not change any underlying resource data. Measurements and tracking which update data may still occur, but the resource data identified by the URI should not change.

Retrive supercar entity with an id = 14:

GET /supercars/14

Retrive supercar entity with an brand = "Honda"and result pagination:

GET /supercars/?brand=honda&limit=10&offset=20

POST

Request that the resource at the URI do something with the provided entity. POST is used to create a new entity, the data are send in the request body and also in query params.

Create a new supercar entity by POST:

POST /supercars

Body:
{
    "brand": "Pegeuot",
    "model": "207",
    "body": 2,
    "year": 2016
}

PUT

Store an entity at an URI, its used updating an existing resource. A PUT request is idempotent and its is the main difference between the expectations of PUT versus a POST request. The difference between the PUT and PATCH methods is that, the PATCH is used only for partial update while PUT for replace an existing entity.

Note:

PUT replaces an existing entity. If only a subset of data elements are provided, the rest will be replaced with empty or null.

Update supercar entity with an id = 14 via PUT request:

PUT /supercars/14

Body:
{
    "brand": "Honda",
    "model": "Odyssey",
    "body": 10,
    "year": 2017
}

DELETE

Request that a resource to be removed. However, the resource does not have to be removed immediately. It could be an asynchronous or long-running request.

Delete an supercar with anid = 1:

DELETE /supercars/1

Besides the four basic HTTP methods, it is also worth mentioning the following two:

PATCH

Update only the specified fields of an entity at a URI. A PATCH request is idempotent.

Note:

In PATCH request we provide only a subset of data to be replaced in the entity.

Update the supercar fields with an id = 14:

PATCH /supercars/14

Body:
{
    "model": "Civic",
    "body": 2
}

OPTIONS

The OPTIONS method represents a request for information about the communication options available on the request/response chain identified by the Request-URI. This method allows the client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval. The OPTION calls are generally initiated automatically by the browser for security and performance reasons.

Media types

In the header of the request, the client sends the type of content that it is able to receive from the server. This is called the accept field, and it ensures that the server does not send data that cannot be understood or processed by the client. The options for types of content are MIME Types.

In cases where the server is sending a data to the client, the server must include acontent-typein the header of the response. This field alerts the client about the type of data it is sending in the response body. Thecontent-typethat the server sends back should be one of the options that the client specified in theacceptfield of the request.

For example, when a client is accessing a resource withid = 14in ansupercarsresource with this GET Request:

GET /supercars/14 HTTP/1.1
Accept: application/json

The server might send back the content with the response header:

HTTP/1.1 200 (OK)
Content-Type: application/json

This would signify that the content requested is being returning in the response body with acontent-typeof application/json, which the client said it would be able to accept.