API Best Practices: Webhooks, Deprecation, and Design
At Zapier we love what APIs make possible, but we also wrestle with them every day. Our developer platform connects to over 1,000 APIs with millions of a calls every day. We run into API downtime, anti-patterns, and deprecations all the time. Here we’ve collected some of the best tips for those providing APIs.
Take Your API Real-time with Webhooks
There’s nothing wrong with the typical GET and POST API lifestyle. When it comes to new data that’s available, we’d like to know sooner than our next scheduled request (we poll every 5-15 minutes, so those add up). Instead, we’d rather see subscription webhooks supported by every API where it makes sense. Webhooks are kind of like a reverse API, letting the consumer know when there’s something new.
» Read Add Webhooks to Your API the Right Way
Stretch Those API Responses How You Like
Limber up and check out these methods for letting API consumers decide what data they want to receive. Some top APIs will allow developers to include or exclude specific values, or choose certain fields to expand with additional data. Rather than deliver all responses the exact same way to every client, consider these three different ways you can help developers declare what they want back from your API.
» Read 3 Ways to Make Your API Responses Flexible
Please Spend Some Effort on Your Documentation
Everyone agrees that great documentation is important, yet it often gets tossed to the end of the list. When choosing between making an API work and making it understandable, the former gets the most effort. A well documented API that doesn’t work is useless, after all. But so is a technically tip-top API that nobody knows about. There are many powerful developer experiences that you can learn from, which we’ve compiled into one of our most popular posts.
» Read 8 Great Examples of Developer Documentation
If Your API Must Go Down, Please Do This
One of our platform partners had a question: what should they do when their API goes down? Try to fix it, we said. What they really meant was sometimes they need to perform maintenance on the database or API server. Avoid that, we said. But then we said, if it’s absolutely necessary, follow these steps…
» Read How to Handle Planned Downtime for Your API
The Dev-Friendly Approach to Inevitable API Deprecation
It’s one thing to have rare, short API downtime. But the day eventually comes for most APIs where they need to be deprecated. Often that means they’re replaced by an updated version. While that’s exciting, it means all of your developers on the old version will need to migrate. That can be a pain to do work that doesn’t feel necessary, so it’s important you help them as much as you can. Surprise deprecations are the worst kind!
» Read API Lifecycle, Versioning, and Deprecation
By the time you’ve followed the advice in these posts, you probably have a pretty great API. There’s a good chance that API is a candidate to connect to our developer platform and the millions of users already automating with Zapier.
Comments powered by Disqus