Considerations for REST APIs

An API, or Application Programming Interface, is a set of rules and protocols. These allow different software applications to communicate and interact with each other.

APIs play a fundamental role in modern software development. This is because they facilitate the integration of disparate systems, enabling the creation of third-party extensions or applications. As well as drive the interoperability that underpins much of today’s digital technology and services.

What is a REST API?

Representational State Transfer (REST) is a software architecture that imposes conditions on how an API should work. REST was initially created as a guideline to manage communication on a complex network like the Internet.  This is the most common type of API and REST offers several advantages. 

Firstly, they utilize a well-defined and standardized set of HTTP methods (GET, POST, PUT, DELETE, etc.). This simplifies the understanding and usage of the API. This makes RESTful APIs easy to learn and work with for developers. 

Secondly, they promote a stateless client-server interaction. This enhances scalability by allowing each request to be independent and self-contained. REST’s resource-based approach encourages a clean and structured design, making it easy to organize and manage resources.

Overall, RESTful APIs offer simplicity, scalability, and compatibility, making them a solid choice for building web services.

REST APIs do have some limitations relating to security. This can be a concern, as REST relies on external standards for authentication and authorization. These can lead to inconsistencies and vulnerabilities if not properly implemented. Despite these issues, REST remains a popular and versatile choice for many API implementations when used appropriately.

REST Query String Capabilities

If you are requesting data from an API sometimes you want a specific object, and sometimes you might want all objects in a data set. However, quite often you’ll want to specify the characteristics of the set of objects to be returned. This is where the greatest opportunity exists to provide flexibility.

A very common requirement is to have returned only those objects that have been modified since a specific date and time. Data is being synchronised and I’m only interested in what has changed since the last time that I checked.  Adding query string parameters to allow for retrieving only those records that have been recently added or recently changed provides a huge advantage to the user of your API.

Sometimes API designers provide special highly flexible query methods that give almost infinite flexibility.

What data should be returned? 

If an object contains many properties, it can be very inefficient to return all the data when a request is received.  This is particularly the case when the API call returns all objects for a large data set. 

Consider allowing the API user to specify which properties are to be returned. This will significantly reduce the amount of data being passed between applications resulting in improved performance.

How much data should be returned/received in a single call?

The API designer needs to consider how much data is returned to the user in a single call and this is known as the ‘page size’. Typically, an API might return 500 objects in a single call.

It can also greatly improve efficiency if bulk postings are provided for too. That means that if many updates are required, they can be made with a single post. Rather than calling an API once for each update. Again, the API designer can set a maximum of the number of updates that can be made in a single API call.

Rate Limiting

The API designer needs to consider the maximum frequency that calls into the API are allowed and this means setting rate limits. 

APIs are rate-limited to control and balance the volume of requests from clients, preventing abuse and ensuring fair resource allocation. Rate limiting helps maintain server stability by preventing overuse or DDoS attacks that could degrade performance or lead to downtime.

It also enforces compliance with usage agreements and cost control measures, ensuring that all users have equitable access while protecting the API provider’s infrastructure and services.

Get to know APIs even better