In our experience, some things work and some things don’t when it comes to APIs. This section offers a few of what we consider solid best practices for API design.
First things first—why should a developer use your API? How is it different from other alternatives? Why should they use it?
Here are some possible ways to differentiate your API:
The data is unique, more complete, or more accurate than that of your competitors
You offer better support or an easier signup process
Your API is more robust, reliable, cooler, or faster than alternatives
Your terms are more developer friendly; perhaps you offer more data traffic for free or at better rates
Emphasize why someone should use your API, rather than an alternative. An alternative could be a competitor’s API for a public API, or an alternative data source or older (and more familiar) technique for a private API. You can also differentiate offerings and incentives around your API. One strategy is to offer different tiers of pricing based on amount or type of usage. This strategy allows you to reach more levels of subscribers. Some API calls can be free, while others may require payment. You could authorize free use of the API in a public-facing app while charging for using it behind a firewall.
If your API is one of many options, your audiences may dedicate only a few minutes to trying it. If they can’t make almost immediate progress, they’ll go elsewhere. ...