Ersin BuckleyMy hands are sweaty as they race across the keyboard. My eyes dart through the stream of log messages going past. There it is! The reason I woke up at 2:30am on a Sunday. A broken API integration caused by an update I didn’t notice was supposed to happen 12 months ago.
So, you are writing a new API product, and I am going to be leading an effort to integrate with it. Read on for my list of what you should be caring about and the must-have features.
TLDR? The most important parts of your api design are:
- Never break backwards compatibility
- Be respectful of performance and stability
- Give me tools for security and access management
- Break the APi with care
- Give me a great onboarding and documentation experience
- Make it gorgeous and easy to understand
Stability and Backwards compatibility
The number one thing that I want from your API is that it never breaks, and my integration just works forever! Be gentle if you are going to break it. Once I have written the code, don’t make me go back and look at it 6 months, 1 year, 5 years later.
10% of effort is spent on implementing successful software and 90% is spent on operation and support. I call this the 10-90 rule. Most blogs, products and new developers focus on making the initial implementation easy. The reality is that business will spend 90% of the effort on operating and supporting a successful integration. An API really explodes this factor because so many external developers are also involved for each partner or customer that uses your product. A significant break in the integration could mean 100’s of developers need to stop and fix something. This level of distraction is churn just waiting to happen.
A surprising example of not breaking the API is Windows. A decades old binary will still run, because of the stellar focus on backwards compatibility. Keeping the ‘classic’ software running is a huge factor in the ongoing enterprise success that windows has. Many small and medium size businesses depend on these niche databases and applications. A huge sector of IT professionals are employed to operate and support them.
How do you avoid breaking backwards changes?
- Use versioning to make sure that deprecated functions are never removed but newer implementations are available.
- Never remove a field from the returned data type.
- Do not rename a field.
- Never re-type a field.
Sticking to these basic rules are the most important thing you can do to make me happy with your API product.
Performance and Scalability
Your API should never cause me a butt-clenching text message or phone call at 1:30am in the morning. To do this, you need to shift my focus to a better implementation which can handle an unexpected increase in the scale or performance of your API.
If a request is slow it should timeout. If it is always slow, it should be asynchronous. Timeouts are super simple to implement, and you can usually just add some configuration to your load balancer for it. To really handle long running requests though you need to have a ‘start the work’ endpoint and a ‘get the work’ endpoint. This is an idempotent approach that allows really easy caching of requests. It will result in less work done by the servers, as holding multiple long running requests open is more likely to result in timeouts and re-running the request.
Rate limiting is another must have for your API. It is important because I will be forced to think about retry logic during implementation, and this will yet again save me from an unplanned late evening wake-up call.
When you are developing the webhook feature, please be kind and provide me options for queuing or load shedding behaviour. I have never implemented a push integration which hasn’t eventually gone haywire at some point. This could mean your product has gone viral (good), or the vendor has gone wild (bad). In either situation I have been extremely grateful for systems put in place ahead of time to handle this load.
How to version and break changes
Never remove or break an API that is still being used. You need to wait at least a year, really! I have actually worked with customers and partners that do a once a year API call. When the yearly call breaks, you can probably figure out what that person thinks about your product when they come to fix it.
Instead of changing the meaning of an existing API, you need to introduce new versions. One easy way to do this is to introduce a new name for the API method. Or if you have a whole suite of breaking changes to endpoints you might mint a major version upgrade in the URL path.
But before you go blasting ahead on your API, I want you to ask yourself.
Do I really need to remove/break that api?
The best way to break it is to get on a call and help every customer using the API to upgrade their integration. If you did this you will be 1000% better than every other company that has an API product. This is something that I think is a very cool way to do something which doesn’t scale, and can delight your customer.
Security and access management
Give me tools to audit, manage and control how API keys are used.
- Adding new keys or revoking old keys
- Setting expiry times for temporary keys
- Setting granular permission for the key
- Seeing the usage of the key
- Setting billing limits
You should care about these features because they will reduce your customer support workload. They help customers when their integration goes wild. If something bad happens, all the important audit data is available through the usage history for the API.
Clear Documentation and onboarding
Every commit that changes the API should come with a changelog update and a new documentation site. Tools like openapi help with the generation of docs and you should consider something similar for your platform. Include all the things, like generated types and field by field data model comments. Offering client libraries I can npm install or go get are nice to have, but not necessary in my opinion.
When I get round to integration of your API I’m going to start with the documentation. This is your opportunity to set me on the right path and make something that is high quality and won’t break on xmas day when I’m enjoying time with my family.
Another amazing thing you could consider here is ‘white glove’ level of service, give me access to a developer who knows your API and can help me integrate. Another opportunity for standing out amongst a field of mediocre at best API products.
Style doesn’t matter but you asked!
Least of all and last in the list is on the API style. HTTP, REST-ish and json formatted is just fine thanks!
I like plain old HTTP because I can call it from just about anything from curl through to any old other programming language.
Using roughly REST (no need to be zealots) style to me means using clear URL paths, and GET/POST/DELETE methods. It is incredibly nice to have cache headers in the response so that I can check if the rest of the body needs to be read or if I can simply wait and query again later for new data.
There are a lot of options for API style, graphQL, protoubf, xml, soap. Style is much less important than any of the other points here. Reason for being chill on API style is that it is more of an implementation factor than a support factor. One style from another doesn’t represent too much difference in the ongoing support of the integration.
Too long, did read
Thank you for taking the time to implement an API in your product, I really appreciate it and I love the ability to integrate and automate on top of the platform. It is important, and will be ever more important to the decision makers and buyers of software to have API functionality.
Most important in your implementation is to respect the 90% of time spent on supporting the API. You should be thinking about this with every increment on the product. We underestimate the pain and time that goes into the operation of software. If you follow my suggestions here your support people will be happy and your customers unburdened.
My favourite type of API integration is the one I do once and think about very little for the next few years.
If you are putting the effort into making an API product you should care about all this stuff like I do! If you don’t care about it but you're reading this anyway maybe we should chat and I can figure out how to help you on your journey.
