REST APIs

Overview

A RESTful API is an application program interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data.

REST technology is generally preferred to the more robust Simple Object Access Protocol (SOAP) technology because REST uses less bandwidth, making it more suitable for internet usage.

REST Advantages and Characteristics

• Stateless Client/Server protocol as based on HTTP protocol.
  each HTTP request/response contains all the needed information to run. No session
  or cache needed.
• Clear separation between client and server. Resources are mapped with URI only.
  That makes the code more scalable and clean as Front-End and Back-end code can run on different servers.
• REST API is independant from the plateform or language used (Java, Python...)
• Only worry about sending the data to an endpoint, no matter the format (XML, JSON, Text).

Safe methods

When designing REST APIs, you should be aware of two very important properties of HTTP methods: idempotency and safety.

An HTTP method is safe if it doesn't alter the state of the server. In other words, a method is safe if it leads to a read-only operation. Several common HTTP methods are safe: GET, HEAD, or OPTIONS. PUT, POST and DELETE are not safe.

Idempotency

Idempotency is a property of HTTP methods. A request with an idempotent HTTP method can be performed multiple times and the same result will be produced. 

Idempotency is important in building a fault-tolerant API. Suppose a client wants to update a resource through POST. Since POST is not a idempotent method, calling it multiple times can result in wrong updates. What would happen if you sent out the POST request to the server, but you get a timeout. Is the resource actually updated? Does the timeout happened during sending the request to the server, or the response to the client? Can we safely retry again, or do we need to figure out first what has happened with the resource?

By using idempotent methods, we do not have to answer this question, but we can safely resend the request until we actually get a response back from the server. 

HTTP Post and Patch are not idempotent.