Today I had the honor to give a training to some of the newly started young professionals in our organisation. The topic of the training was API design in ASP.NET Core. During this training we discussed multiple topics and a lot of interesting questions were raised. I'll try to tackle some of them with a blog post.
Let's start with a first question and immediatelly a controversial one...
What is REST?
Let's first have a look at what Wikipedia has to say about REST:
Representational state transfer (REST) is a software architectural style that describes a uniform interface between physically separate components, often across the Internet in a Client-Server architecture.
It was originally introduced in a dissertation by Roy Fielding titled 'Architectural Styles and the Design of Network-based Software Architectures’. Here is the link if you like to read it: https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm.
What is most important to understand is that REST is an architecture style, NOT a standard.
Let’s walk through the six constraints:
Client–server architecture
In the REST architectural style, the implementation of the client and the implementation of the server can be done independently without each knowing about the other. This means that the code on the client side can be changed at any time without affecting the operation of the server, and the code on the server side can be changed without affecting the operation of the client.
As long as each side knows what format of messages to send to the other, they can be kept separate.
Statelessness
Systems that follow the REST paradigm are stateless, meaning that the server does not need to know anything about what state the client is in and vice versa. In this way, both the server and the client can understand any message received, even without seeing previous messages. This constraint of statelessness is enforced through the use of resources, rather than commands. Resources are the nouns of the Web - they describe any object, document, or thing that you may need to store or send to other services.
Cacheability
When possible, resources should be cacheable on the client or server side. Server responses also need to contain information about whether caching is allowed for the delivered resource. The goal is to improve performance on the client side, while increasing scalability on the server side.
Layered system
In REST APIs, the calls and responses go through different layers. As a rule of thumb, don’t assume that the client and server applications connect directly to each other. There may be a number of different intermediaries in the communication loop (firewalls, routers, reverse proxies, …). REST APIs need to be designed so that neither the client nor the server can tell whether it communicates with the end application or an intermediary.
Uniform interface
All API requests for the same resource should look the same, no matter where the request comes from. The REST API should ensure that the same piece of data, such as the address of a user, belongs to only one uniform resource identifier (URI).
Code on demand (optional)
REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This simplifies clients by reducing the number of features required to be pre-implemented. Allowing features to be downloaded after deployment improves system extensibility. However, it also reduces visibility, and thus is only an optional constraint within REST.
Truly RESTful
Although 5 of them are necessary to call a system truly RESTful, typically any Web API that uses HTTP methods and URL’s to point to resources REST is called a REST API (hence all the controversy).
Tomorrow I’ll introduce the Richardson Maturity Model as a way to identify how REST compliant your Web API is.