REST APIs - What You Need to Know

If you’ve spent time on developer forums like StackOverflow, you have probably come across the term “REST API” a few times. Today we’ll go over what they are, why they exist and how they’re used.

Quick Recap of APIs

As mentioned previously, an API, or Application Programming Interface, provides a standard for different programs and/or computer systems to communicate. It allows developers to make use of other developers’ software in a secure and reliable way, and it safely abstracts the API provider’s internal implementation details from developers.

APIs can be designed in different ways to cater to specific use cases. As is the case with most computer science concepts, it’s all about trade-offs. There is no single design that will always be the best choice, but there are a few that developers seem to love. One such popular design is the REST API.

What is REST?

REST is an architectural style (a set of design constraints). It’s an acronym for REpresentation State Transfer, and, as of the time this article was written, it is the most common design choice for most APIs.

For an API to be a REST (or RESTful) API, it has to adhere to six distinct principles:

1. Client-Server Separation

The client application making requests and the server application responding to requests must be completely separate. The client should only know the URI of the API resource (how to call the API) and have no other interaction with the server. Likewise, the server should only be sending information to the client via responses to API requests.

2. Statelessness

REST APIs are stateless, meaning that every request is self-contained and carries all the information needed for the server to do something meaningful. The server should not have to remember any previous request to serve a current request.

3. Uniform Interface

Requests for an API resource should look the same, regardless of what client application(s) are making the API call. This ensures the API can support as many clients as possible, which also increases usability.

4. Cacheable

Caching responses to requests on both client and server applications can both greatly benefit cost and performance.

For servers, if requests for the same resource with the same parameters are constantly coming in, caching results (in a local database, for example) instead of running the full computation each time can save tons of compute time, which often translates into $ savings for cloud provider users (AWS, Google Cloud, Microsoft Azure, etc.).

For clients, it may also make sense to cache data instead of making the same API call over and over again (just make sure the API’s terms and conditions allow it!).

5. Layered System

The server should be structured in a layered way such that the client only interacts with one layer. Other layers (such as load balancing, security and authentication) are completely invisible to the client.

6. Code on Demand (optional)

If desired, the server can send executable code instead of static data such as text or files to the client.

Why You Should Use REST APIs

There are many advantages to working with REST APIs - here are a few top picks:

Scalability

Because of the statelessness principle, servers do not need to worry about storing information from client requests. This makes the entire API more scalable as the amount of work servers need to do will more or less directly correlate with the number of incoming requests.

Flexibility

As long as API creators adhere to the six principles above, they essentially have free reign to design their APIs however they think is best. There is a lot of flexibility here, and compared to other designs like SOAP (Simple Object Access Protocol), REST APIs have much fewer constraints.

Everyone else is using it!

Yes, this last one is somewhat of a self-fulfilling prophecy, but the fact that millions of developers worldwide work with REST APIs everyday does matter. A lot. Client-side developers working with REST APIs can build applications more efficiently and confidently, and API providers developing REST APIs can readily access a huge pool of potential users already familiar with the architecture.

Why You Should Avoid REST APIs

Of course, REST APIs are not perfect. The main drawback of a REST API is its statelessness (yes, the same statelessness principle outlined above). By eliminating state, servers are unable to support any requests involving the history of the API.

For example, consider an API that just returns the previous 3 requests as the response to any current request. The API cannot function without violating the statelessness principle, so in this case using a REST architecture may not make sense.