---
title: "API Best Practices: Webhooks, Deprecation, and Design"
description: "Provides recommendations for building scalable and developer-friendly APIs.
"
---

# API Best Practices: Webhooks, Deprecation, and Design

Provides recommendations for building scalable and developer-friendly APIs.


At Zapier we love what APIs make possible, but we also wrestle with them every day. Our [developer platform](https://zapier.com/developer/documentation/v2/) 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](https://zapier.com/engineering/webhook-design/)

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_](https://zapier.com/engineering/webhook-design/)

## [Stretch Those API Responses How You Like](https://zapier.com/engineering/flexible-api-responses/)

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_](https://zapier.com/engineering/flexible-api-responses/)

## [Please Spend Some Effort on Your Documentation](https://zapier.com/engineering/great-documentation-examples/)

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_](https://zapier.com/engineering/great-documentation-examples/)

## [If Your API Must Go Down, Please Do This](https://zapier.com/engineering/api-planned-downtime/)

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_](https://zapier.com/engineering/api-planned-downtime/)

## [The Dev-Friendly Approach to Inevitable API Deprecation](https://zapier.com/engineering/api-geriatrics/)

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_](https://zapier.com/engineering/api-geriatrics/)

---

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](https://zapier.com/developer/documentation/v2/) and the millions of users already automating with Zapier.