Resource Oriented APIs

Guide to understanding resource oriented APIs and what makes them a good choice over RPC oriented APIs

Introduction

With the creation of APIs, there have been several design paradigms over time which have ruled API patterns such as SOAP, REST etc. But all of them have originated from the basic fundamental understanding of what an API serves. Over time, developers have shifted from creating a method name based on user actions to standard HTTP paradigms of API development. Let’s dive deeper into what these concepts mean and why resource oriented APIs are better than others.

What is RPC-oriented API?

When we call a function (or procedure) hosted on a different computer (could be a far away computer) it is called Remote Procedure Call or RPC. When an api serves user requests in a similar manner, we term those APIs as RPC oriented API. For example, say there is an encryption function that we want to call, encryptString(“hello“) which is hosted on some remote computer and the primary purpose of this function is to serve encrypted data.

RPC oriented APIs are driven by the actions performed and hence, their strength eventually becomes their biggest drawback because if different APIs are used to perform several user actions, then it becomes difficult for them to remember these. For example, if anyone wants to use a library, say Lodash, you will come across several methods such as _.partition, _.remove, etc. It’s difficult to remember all such method calls that perform an action.

What is Resource oriented API?

To mitigate above drawbacks, APIs moved towards standardizing the user actions with verbs such as GET, UPDATE, DELETE, etc. It helps in reusing the API noun with the appropriate verb and reduces the stress to learn them all. For example, if we have travel website with an object Travel that has certain properties like flight information, customer information, etc. then we can create resource oriented APIs around it for say create<Travel> that creates a booking, update<Travel> for updating the same booking, etc. This makes API development a lot simpler for developers trying to integrate with travel APIs

What makes Resource-oriented APIs better?

There are several factors that help in determining if an API is good or not. A few key metrics are:

  1. Operationally Capable: A good API should be able to expose all the capabilities of it’s underlying system and perform actions as intended. For example, if an API is suppose to find top 10 words from an article, it should be able to do correctly and in time.

  2. Simplicity: An API should be easy to understand and use, The resource-oriented way makes it a lot simpler for users to understand actions that can be performed via a single API instead of remembering method names for different actions.

  3. Predictable: An API should behave as expected and API definition and it’s intended behavior should not change drastically.

Although these are commonly used factors to determine goodness of an API, a resource-oriented approach makes API integration smoother when compared to RPC based approach.

Conclusion

Over time, resource oriented approach has evolved into a more sophisticated and better adopted paradigm, REST. But, the concepts around it have majorly remained the same.


If you like the post, share and subscribe to the newsletter to stay up to date with tech/product musings.

(The contents of this blog are of my personal opinion and/or self-reading a bunch of articles and in no way influenced by my employer.)