Over the years, I’ve integrated countless 3rd party APIs into codebases. I’ve used these 3rd party APIs for payments, sending emails, getting information from data providers, among many other things. Those experiences informed my opinions about the attributes I find desirable in an API. This post is a list of those attributes.
These attributes influence whether the developer experience of using the 3rd party API is pleasant. The developer experience affects how easy it is to integrate (i.e., the initial setup) and operate (i.e., the ongoing maintenance burden).
Correctness
Does the API do what it is supposed to do? Does it behave the way you expected it to behave? This attribute is self-explanatory and obvious. Most APIs do this unless when there is a bug.
Reliability
What is the availability of this API? How often is it unavailable? Can we depend on this API for our critical funnels?
The less reliable an API is, the more integration work is needed to ensure that the 3rd party API does not negatively affect my service. Things like aggressive timeouts, circuit breakers, and graceful service degradation are usually added as a response to unreliable 3rd party APIs even though they are desirable on any integration.
Bonus points for vendors that send email notifications when their service degrades.
Performance
How fast are the endpoints? This is particularly important on funnels sensitive to latency (e.g., checkout)
Support
Can you get an answer when things aren’t behaving as expected? How quickly can you get help? How useful is the help you can get? How much supporting evidence do you need to submit when there is an issue?
Sooner or later, you’ll need help, and it better be good. It is crazy how many vendors drop the ball on this.
Documentation
Is there documentation? What is the format of the documentation (e.g., webpage, PDF)? Is the documentation clear? Does the documentation address the most common questions when integrating/operating? How quickly can you test what you learn from the docs?
The better documentation, the fewer times you have to reach out to support.
Usability
How easy is it to integrate with the API? Does the API use a convenient protocol? Does the API respect popular conventions (e.g., status codes, HTTP verbs)? Is there an official library of the API for your language of choice you can use, or do you have to write a wrapper? Is it a pull or a push API? Are the API concepts easy to grasp?
Observability
This attribute isn’t descriptive of the API itself but of its dashboard. Does the dashboard have useful information to debug the API (e.g., request/response logs, errors, fulfillment)? Does the dashboard have usage details (e.g., costs, latency, throughput)?
Trustworthy
Does the vendor roll out changes in a responsible manner? When old versions or protocols are deprecated, how long is the grace period? When there are issues with the payment method, is the service immediately removed?
Which attributes of APIs do you find desirable?
I can send you my posts straight to your e-mail inbox if you sign up for my newsletter.