API best practices can be any tips your development team wants to communicate to developers about working with APIs. There is no set number of topics that are typically covered in API best practices. Instead, best practices can be a general heading for content that doesn’t fit anywhere else.
What topics to include in Best practices
While many of the topics in API documentation are standard, there is usually a detailed list of things you need to know about working with APIs. This information is only available upon request from developers.
The list of topics may include topics such as:
- pagination,
- time ranges,
- fault tolerance,
- cache values,
- connectivity,
- timeouts,
- downtime,
- SSL,
- versions,
- testing and validation,
- exports,
- languages,
- number processing,
- resource expansion,
- notifications,
- CORS,
- localization
- and more.
Mailchimp
Mailchimp API best practices include tips on fault tolerance, using specific requests, authentication, cache values, connectivity, and registration. With fault tolerance, Mailchimp reminds developers that downtime sometimes happens, so they should plan to handle scripting accordingly if the API fails to respond. With ad-hoc queries, Mailchimp alerts users to the time it may take if a query is too generic and therefore returns too much information.
Coinbase
Coinbase does not link to topics such as best practices; instead, the navigation bar shows a list of topics. Pagination is one of these topics worth focusing on. How does pagination relate to the API? Suppose an API endpoint returns all the items in a user’s account. There could be thousands of items, and if all items were returned in a single response, it could take a long time for the API to collect and return a lot of data. As a result, like a Google search, the response returns a limited set, such as the first ten items, and then contains a URL that can be used to navigate to the next set of responses. Pagination refers to navigating to the next page of responses.
Earlier, defining the characteristics of REST, HATEOS or “Hypermedia as an application state engine” was mentioned. Links in responses that return more results are one example of HATEOS.
Programmatically processing a URL to get more responses can be quite a challenge. If you want all items returned and then filtered and sorted by finding specific values to retrieve, how would you do this using the URL returned in the response? The team can advise developers working with these scripts. Most likely, the endpoint will offer filters as parameters to apply to the endpoint so that the initial response contains the desired set of elements. This type of advice may be appropriate in API best practices.