5.3 Strengths and Weaknesses of REST

Now that we have illustrated what a REST API is, and how developers can interact with REST APIs, it is important to discuss the characteristics are that have made REST so successful, and what shortcomings are threatening its sustainability going forward.

• Strengths:

  • Flexible across languages and frameworks: One obvious reason why the REST API has been so successful is that it works across languages and frameworks. No matter how developers build their applications, a REST API will work for them.

  • High interpretability: The fact that REST APIs are URL-based, where each URL gives access to a certain amount of information, renders REST APIs incredibly simple to interpret. All a third-party developer requires is a URL, an understanding of what information they will find there, and an understanding of how they can interact with that information.

  • Server-side Logic: For a company building a REST API, its URL driven nature is extremely simple to work with. The server-side developers simply define a URL where they want certain information to be visible, write logic for how to handle each type of request, and the endpoint is created. However, as a company's API scales in usage, figuring out the optimal way to structure endpoints and the information they provide increases in complexity, a relative weakness of this architecture, transitioning to our next section.

• Weaknesses:

  • Multiple Round Trip (Latency): The client will often need to execute multiple trips to the server to fetch all of the information the client requires. Each endpoint specifies a fixed amount of information, and in many cases that information is only a subset of what a client requires to populate the client’s page. As exhibited in Figure 5.2.1 above, what if the client wished to display the users image as well as their nickname in the client’s application? The client send a GET request for the users information, thus obtaining the location of the users image from the response, and then send another GET request for the image URL. Every time the client executes an extra request, another trip needs to be made back and forth to the server, which requires additional time and thus weakens user experience.

  • Verbose: When a client makes a request via a REST API, the developer will get back all of the information stored there, even if the developer doesn’t need all of it. For example, if a client is only interested in the name and age of a user on Facebook, when the client queries Facebook’s API, the client will get this information, but will also receive all of the other information associated with that user endpoint, such as the user’s profile picture, city of residence, email address, etc. This leads to the transfer of excess information, which causes the client to filter which parts of the response the client wishes to utilize, increasing the time to provide the end-user experience. Though developers have established numerous methods to solve the problem of REST excess, the excess still always adds significant overhead for client-side developers, as the client-side developers need to make a lot of edge cases for certain parameters being passed through.

  • Security with Multiple Endpoints: Given that each endpoint is static and contains only a small set of information, the number of endpoints scales almost linearly with the amount of information servers wish to expose. Thus, popular web applications tend to build out a significant number of endpoints. This is a nightmare for data security, as companies have hundreds of different access points to their server-side logic, and bad-actors will search for vulnerabilities across each one of them.

  • Documentation: One of the biggest drawbacks of REST APIs is that they are schema-less, which means client-side developers have no idea what data structure will be returned when querying an API. There is no way to understand from the endpoint itself what the client will be receiving, and as such the back-end server-side developers must maintain robust documentation to give their users an idea of what to expect. This can be a nightmare to do, especially if the server-side developers attempt to document their API retroactively, and can also lead to slow ramp times for new developers coming in. This is far from an impossible problem to solve, but still a headache to contend with when working with REST.

  • Updates: In practice, a significant number of endpoints are designed on the go, with the frontend server-side team reaching out to the backend server-side team with their data requirements, consequently building an endpoint for them. This introduces significant overhead in the software development process. Every design iteration on the frontend that involves a change in the displayed data needs to go through a process where the backend team is directly involved, which can render APIs brittle and error prone. APIs that are frequently changing are hard to maintain and clients will have a hard time procuring the desired data. When fields are removed from certain API responses without the client being aware of it (the client was simply not alerted and is still running against an older API version), there’s a high probability that the client’s program will crash at runtime due to missing data.

Thus, although REST APIs pose significant positives, and are by far the most universal type of API in the world today, there exist significant drawbacks to implementing it at scale. Whilst these problems were less common 10-20 years ago, as APIs were less ubiquitous and the amount of data being transferred was smaller, REST’s problems are becoming increasingly serious for modern developers. GraphQL, an open-source project developed by Facebook, deals with a lot of these issues whilst still maintaining the strengths that made REST APIs as popular as they have become. After taking a further look, we hope to convince you that GraphQL is in fact the future of API development.