Understanding REST

REST was introduced and defined in 2000 by Roy Fielding in his doctoral dissertation. REST is an architectural style that defines a set of constraints and properties based on HTTP. It is stateless, having a client/server relationship, and a uniform interface.

What is HTTP

The Hypertext Transfer Protocol (HTTP) is designed to enable communications between clients and servers. HTTP works as a request-response protocol between a client and server.

A web browser may be the client, and an application on a computer that hosts a web site may be the server.

HTTP methods

The two most common HTTP methods are: GET and POST.

• GET
• POST
• PUT
• PATCH
• DELETE
• HEAD
• OPTION
• TRACE

GET

GET is used to retrieve data from a specified resource. GET requests must be safe and idempotent, meaning regardless of how many times it repeats with the same parameters, the results are the same.

Retrieve an address with an ID of 1:

 GET /addresses/1

POST

POST is used to send data to a server to create/update a resource.

The data sent to the server with POST is stored in the request body of the HTTP request

Create a new address:

 POST /addresses

PUT

PUT is used to send data to a server to create/update a resource. A PUT request is idempotent. Idempotency is the main difference between the expectations of PUT versus a POST request.

Modify the address with an ID of 1:

 PUT /addresses/1

PATCH

PATCH is used to update only the specified fields of a resource. A PATCH request is idempotent.

 PATCH /addresses/1

DELETE

DELETE is used to remove all target resource; however, the resource does not have to be removed immediately. It could be an asynchronous or long-running request.

Delete an address with an ID of 1:

 DELETE /addresses/1

HEAD

HEAD is almost identical to GET, but without the response body.

HEAD requests are useful for checking what a GET request will return before actually making a GET request - like before downloading a large file or response body.

HEAD an address with an ID of 1:

 HEAD /addresses/1

OPTION

The OPTIONS method describes the communication options for the target resource.

TRACE

The HTTP TRACE method performs a message loop-back test along the path to the target resource, providing a useful debugging mechanism.

HTTP status codes

Status codes indicate the result of the HTTP request.

• 1XX - informational
• 2XX - success
• 3XX - redirection
• 4XX - client error
• 5XX - server error

Media types

HTTP headers can be used to describe the content being sent or requested within an HTTP request. The client may set Accept to application/json if it is requesting a response in JSON. Conversely, when sending data, setting the Content-Type to application/xml tells the client that the data being sent in the request is XML.