Dear API Providers - Misir's Blog
I writing this article as a manifestation and a cry for help to everyone being involved in designing and serving APIs to be consumed by external consumers.
Please, just maintain stability of your APIs, don’t change name of a field because of some internal reason I am not concerned about, or heck don’t move the entire body into another object just because you can now claim to have a cleaner API design. As a consumer, the last thing I would care about is what are your internal struggles, struggles that are undocumented and have not been disclosed during integration phrase. Consumers want a peace of mind and stability. Otherwise changing software to fit third party’s changing needs is costly and time consuming exercise.
Here, I will be sharing my experience working with lots of third party service providers ranging from CRMs, payment services, well known services like Firebase, to internal providers from another department within the same company.
Let me start from the last two points, where the pain started hitting when I first started integrating the provider. Third party API integration documentations are a common pain point among many service providers; they usually lack the empathy necessary to look at the problem from the consumer’s perspective and write out what they need.
