Building RESTful API: all you need to know

REST stands for Representational State Transfer. It is a set of design principles for making network communication more scalable and flexible. REST definition outlines a number of architectural constraints that a system must satisfy to be considered RESTful.

Comparing SOA web service interfacing style of SOAP vs. REST, the former tend to be centered around operations that are usually use-case specific and specialized. In contrast, REST is centered around business (data) entities exposed as resources that are identified via URIs and can be manipulated via standardized CRUD-like methods using different representations, and hypermedia.

Among bunch of HTTP request methods, developers normally use GET and POST methods for forms.

GET Method

• Should be used to get (request) data from a resource
• Sends data with the URL as key-value pairs
• Should be used to retrieve data from a resource
• Never used to send sensitive data
• Less secure than POST but faster
• Different data creates different URLs
• Can be cached in the browser. However, random data (timestamp) can be used to bypass cache
• Remains in the browser history
• Has length limitations, maximum URI size of 4796 bytes
• Only ASCII data

POST/PUT methods

• Should be used to post data to the server
• Should be used to send sensitive data
• Slower than GET, but more secure
• Sends data with body of the HTTP message
• Does not remain in the browser history
• No length limitations
• Any kind of data can be sent

If you are sending sensitive data such as passwords, emails with HTTP request you must use POST or PUT. If you are retrieving data from the server, you can use GET method.

Resource Methods and responses

Though, because REST also intends to make the web (internet) more streamline and standard, Roy Fielding, author of REST, advocates using REST principles more strictly. And that's from where people try to start comparing REST with web (HTTP).

Resource methods to be used to perform the desired transition. A large number of people wrongly relate resource methods to HTTP GET/PUT/POST/DELETE methods. It has been never mentioned any recommendation around which method to be used in which condition. All what was emphasized is that it should be uniform interface. If you decide HTTP POST will be used for updating a resource – rather than most people recommend HTTP PUT – it's alright and application interface will be RESTful.

However, despite all the theory, the classic REST that is now used for web applications is highly dependent on the HTTP protocol. Here is the most common implementation:

• fetch multiple entries from a resource
  • Request GET /resources
  • Response -> Returns a banch of resources with 200 OK code
• create new entry
  • Request POST /resources with JSON payload in the body
  • Response -> Returns newly created resource with 201 Created
• fetch single entry for a resource
  • Request GET /resources/{:id}
  • Response -> Returns a single entry with 200 OK
• update single entry of single value of resource
  • Request PUT /resources/{:id} with JSON payload in the body
  • Response -> Returns updated resource with 200 OK or empty body with 204 No Content
• update multiple entries (rarely used)
  • Request PATCH /resources
  • Response -> Returns updated banch of resources with 200 OK or empty body with 204 No Content
• delete resource
  • Request DELETE /resources/{:id}
  • Response -> Returns an empty body with 204 No Content

One transaction for an API will consist of at least the following:

• Request method
• Request path
• Request body
• Response code
• Response body

Many responded positively to this paradigm and began to use it in the development of web services using HTTP. This is what we call the RESTful API.

RESTful technology has become very popular for the web as a whole, and is used even more broadly than originally planned. In addition to working with the API (processing only data), the REST contract for building requests and responses is also often used for classic web page loading. Yes, it's worth agreeing with the fact that this is not a theoretically correct REST, but a classically recognized one.

REST Constraints

The network must be made up of clients and servers. A server is a computer that has resources of interest, and a client is a computer that wants to interact with the resources stored on the server. REST requires one-to-one communication, so event-based integration architecture would not be RESTful.

REST is about stateless server and stateful communication, so you should transfer your state with every request. Each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client and it should come with request. The best approach for nowadays is JWT usage introduced as an alternative to the server-side session storage. You can securely transfer state and be sure it was not modified by client.

Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests.

The "uniform interface"" constraint ensures that there is a common language between servers and clients that allows each part to be swapped out or modified without breaking the entire system. This is achieved through 4 sub-constraints: identification of resources, manipulation of resources through representations, self-descriptive messages, and hypermedia.

It MUST not break backward compatibility

Change APIs, but keep all consumers running. Consumers usually have independent release lifecycles, focus on stability, and avoid changes that do not provide additional value. APIs are contracts between service providers and service consumers that cannot be broken via unilateral decisions.

There are two techniques to change APIs without breaking them:

• follow rules for compatible extensions
• introduce new API versions and still support older versions

When changing your RESTful APIs, do so in a compatible way and avoid generating additional API versions. Multiple versions can significantly complicate understanding, testing, maintaining, evolving, operating and releasing our systems (supplementary reading).

If changing an API can’t be done in a compatible way, then proceed in one of these three ways:

• create a new resource (variant) in addition to the old resource variant
• create a new service endpoint — i.e. a new application with a new API (with a new domain name)
• create a new API version supported in parallel with the old API by the same microservice

It should define and assign permissions (scopes)

APIs must define permissions to protect their resources. Thus, at least one permission must be assigned to each endpoint.

APIs should stick to component specific permissions without resource extension to avoid governance complexity of too many fine grained permissions. For the majority of use cases, restricting access to specific API endpoints using read and write is sufficient for controlling access for client types like merchant or retailer business partners, customers or operational staff. However, in some situations, where the API serves different types of resources for different owners, resource specific scopes may make sense.

JSON-pure API as an alternative

JSON-pure API (aka Web API) offers us the following:

• It uses just one transmission method to send a request - typically POST for HTTP or a send for WebSockets.
• It completely separates the request content from the transmission mechanism. All errors, warnings, and data are placed in the JSON request payload.
• It uses only one response code to confirm proper receipt of a message - typically 200 OK for HTTP.
• It completely separates the response content from the transmission mechanism. All errors, warnings, and data are placed in the JSON response payload.
• It is easy to debug since transaction information is found in easy-to-read JSON inside the payloads using a single, domain specific vocabulary.
• It can easily be moved or shared between transmission channels such as HTTP/S, WebSockets, XMPP, telnet, SFTP, SCP, or SSH.