Learning somebody else’s APIs — What is the most important thing?

We all have been on projects when you have to learn somebody else’s APIs in order to accomplish the requirements that you were given.

Yes, you need to first see if they are SOAP or RESTful APIs. Then you are most likely curious if the response from these APIs is XML or JSON. Then you analyze the elegance of the input parameters and how the GET/POST/PUT/DELETE https calls work for each API. Then you learn about the security for these APIs and what you as the client have to do.

However, the most important thing that you need to watch out in consuming other APIs is how they work together in a flow. What do I mean by this? APIs when investigated in a standalone way may all look good, but how do they work in a flow and can you connect them together without complicating your design?

For example, you may provide me a “Customers” API that allows me to create a customer. You also provide me a “Subscriptions” API that allows me to create a subscription for the given customer. Let’s assume that you neglected to return the subscriptionId in the successful response for the creation of the subscription. Now I don’t have the subscriptionId and I need to connect some of my data with the subscriptionId that you should’ve returned to me before I can give my customer the access to the subscription features. You may provide a mechanism for me to get this subscriptionId in near time by listening to some events from your system, but this means that I have to implement this whole near-time capability in my system and plus the near-time solution may not be good enough for me because the customer is waiting in the browser and I cannot technically proceed without connecting my records with your subscriptionId as I will increase the chance of ending up with orphan records.

Do you see how a simple lack of subscriptionId in the response of the Subscriptions (POST) API introduces complexities in the flow of your application? This is just a simple example, but there are more complicated cases that you can detect as you get deeper into analyzing somebody else’s APIs. You may have some flexibility if the APIs you are trying to consume are developed within your company, but if these APIs are from an external vendor, then your decisions may be affected in the negotiation with this vendor.

Please pay attention to this as the consumer of somebody else’s APIs and if you are developing APIs for others to consume, then try to keep it simple for your clients so that their flows are simple.

Thank you for reading.

Almir Mustafic.