Although there are many discussions around REST APIs regarding the functionality they provide or whether it is useful, many simply try to understand what is its meaning and what it offers. This blog can serve as an entry point to everyone who is joining the web development community as it answers what REST (and RESTful) is, how it is different, are there any challenges coming with it, what benefits does it offer, and should you use it.
What is an API
An API (Application Programming Interface) is a software intermediary, which allows communication between two applications. It is often called a contract between a provider and a user – the content the user gives and the content the provider requires. It’s a connection between the clients and the resources a specific organisation provides.
The biggest advantages are that you don’t need to know how your resource is retrieved or where it comes from while maintaining security and authentication as you can decide who gets access to what.
REST is a set of architectural constraints created by Roy Fielding. It does not add any functionality to HTTP – REST is an architectural style that was developed alongside it and commonly uses it for its application layer protocol.
The following architectural requirements need to be met if we want to consider an API as a REST API:
- Client-server architecture with resources and managed requests. The server would manage application data and state and communicate with a client to handle the user’s requests – a clear separation must be present.
- Stateless – no client information should be stored between requests and every request is independent in terms of connection.
- Cacheable data – servers must have marked their responses as cacheable or not so that the client can cache them whenever possible to improve performance.
- Uniform interface – services must provide data as resources with consistent namespace – this includes self-descriptive messages returned to the client with enough information and resource manipulation from the client via a representation they were given.
- Layered system – invisible to the client, a system in which each type of server (security, for example) is organised into hierarchies.
These constraints combine to form an application with solid boundaries and a clear separation of concerns. The client receives server data when requested and can manipulate or display it. The architecture hides implementations, without concealing data.
New technology is released and generally becomes commonly used just because it is better. Although REST APIs have been here for a while, they still come with their challenges:
- Validating REST API parameters – because we do not know who would use the API, we can expect that the parameters might not fit the value ranges or the expected data type, which could trigger system crashes.
- Securing API calls sequences – whenever multiple calls are being invoked, if they are not handled in the correct order (if there is ordering), the system could crash, which is something that software developers need to keep in mind.
- API testing
- First, developers perform manual testing to see if something is working. Automated tests are also required but to see how well the APIs would perform under pressure and the initial setup for testing could sometimes be quite unpleasant.
- After the initial setup, any changes in a specific API must be also addressed and changed in the testing schema – in terms of parameters for example.
- Testing different parameter combinations with different types to observe how the server handles it could also be a bummer as with more parameters the combinations grow.
To REST or not to REST
REST APIs are better for building applications when it comes to scalability in the future. They are not concerned with client-side technology, which means they can work on different platforms seamlessly or with minimal changes. This could result in better app development as you are not concerned with a specific OS or device in mind but rather with the development of the application itself. Its feature set and core development are put on primary focus instead, therefore the lifespan of the application would be generally longer.
Another key point here is caching – it also contributes to scalability as it reduces the number of calls that must be made, thus reducing the network bandwidth. This way the services can process more requests with fewer resources.
However helpful stateless architecture might be, it is also limiting – it allows you easily to change servers thus increasing the system lifespan but on the other hand all requests need to include all of the data in the message payload, which is fine for a small amount of data but it gets quickly unmanageable for complex requests when the payload size is enormous.
In conclusion, REST is a quite helpful tool and a generally good rule to follow but you should not enforce using it if it does not suit your goals or if the architecture does not allow you to do so.