Recently, I saw a tweet from an angry engineer who rightly pointed out the boundary limits that are seldom followed in designing APIs. Honestly, I hadn’t given much thought to API designing principles before seeing that tweet but I did have a few concerns in the past with respect to the changing rules in defining the API contracts. It was like, depending on who is designing the API, within the same team there exist multiple rules.
I see principles and manifestos as a guideline, something human beings can refer to, to get on the right track. It also helps in maintaining the same semantics across the team, org-wide, and most importantly industry-wide.
In this article, we will learn to differentiate between the different APIs and also the best practices that could be followed.
What is an API?
An API is an Interface. Application Programming Interface that is.
As the REST APIs started to gain attention, an API is often mistaken with a REST API. They are not the same.
An API could be any interface that helps communication between two programs. The most popular examples are Java SE and JDK APIs. Both these modules of the Java platform define a set of classes and interfaces that user-defined programs can use based on their need.
What is a REST API?
An API that follows the principles of REST Architectural Style.
Having said that, REST API as we know it today is not the original architecture that was created by Computer Scientist Roy Thomas Fielding. He even wrote an entire blog to vent out his frustration on calling any HTTP API a REST API.
Most of what was designed by Mr. Fielding as a REST API later became HATEOAS REST and the common adaptation of REST Architecture is a deviation from its original design.
REST API and Backend HTTP API
At this point, I’m not even sure how to differentiate between these varieties of HTTP API calls but for the ease of understanding, I would let it be.
A REST API in its current popular form is an entry point to many services that were designed and developed by multiple enterprises and as a part of OSS projects.
Let’s take Twitter API as an example. Twitter exposes its endpoints to developers and other applications to consume its services when your application wants to post a tweet or wants to collect the analytics etc. These APIs are not specifically designed for one consumer, they are exposed for so and so reason and are open to being consumed by any applications. This example is a perfect use case for a standard REST API.
A Backend API is anything one develops to support a specific Front End of an application. Now it could be consumed by one or many front-end platforms but the sole purpose is to serve a particular enterprise’s customers.
Let’s take Walmart as an example. Walmart’s website can be accessed on the web and mobile as an app and website. It will have a separate login for customers and employees. Most of the APIs created in this case would be to support these front-end, customer-facing applications. These endpoints are backend APIs. They do not follow the same set of principles that the publicly exposed APIs do and they change as the front-end system’s requirements change.
Design Guidelines
Few guidelines that publicly available REST API’s follow would include,
- Proper use of HTTP Verbs
- A defined set of success and error codes
- API versioning (check Twitter API’s v1 and v2 )
- Proper documentation
Any major changes introduced to these APIs will be released in a different version of the API so the consumer knows which version to consume for their needs. A backend API on the other hand needs to change based on the changing requirements of the front end and mostly these APIs do not maintain a version.
Conclusion
I hope this article helps to get a basic understanding of APIs.
Do read the articles and blogs of Roy Fielding and Martin Fowler to get a better understanding of software and networking concepts. It would also help us to see how an industry like ours is greatly driven by misinterpretations 😉
Suggested Read
Roy Fielding’s Blog on REST Architecture— https://bit.ly/3HlWol1