At Bearer, we read tons of API documentation (docs). The good, the bad, and everything in-between.
Along the way, we've learned a few techniques to get the most out of an API's documentation in the shortest period of time. After all, your focus should be on building your app, not struggling with someone else's.
Here are some ways our team approaches understanding a new API's documentation.
The overview is always a good place to begin. This is often the landing page of the documentation. It has guidance on basic usage, authentication methods, common errors, and any quirks or unique aspects to the API. You'll want to make note of the following in particular:
Stripe's docs are a great example of starting with the common use cases and guiding users.
As many API providers shift toward more "use case" approaches to documentation, it is still valuable to keep the API reference section on hand. This portion of the docs contains a complete list of methods and endpoints, along with their request and response objects. Sometimes this will be referred to as the API reference, the list of endpoints/resources, or the method reference.
REST APIswill normally provide a list of endpoints and their available actions, or a list of resources and their available methods.
Google Calendar's API reference focuses on the methods of each resource such as
for the CalendarList instead of a list of endpoints and HTTP Verbs.
GraphQL APIsfocus more on types, query methods, mutation methods, and any custom additions on top of the GraphQL spec.
Shopify's GraphQL Storefront API provides each query and mutation available, as well as custom scalar types.
Many APIs will include an API Explorer , sometimes called the console . This allows you to perform calls against the API's resources as you view the documentation. Think of it as a no-code approach to exploring an API.
Explorers are a very powerful way of helping developers get used to a new endpoint, the required parameters, and how the response will be structured. As you begin to integrate an API, it is the easiest way to run a quick request and validate the API response. No need to open your IDE or launch Postman and configure authentication.
On Google's APIs, the explorer lives alongside each resource.
Our favorite documentation sites put the user first.
Twilio takes the split approach in showing information about a resource alongside code examples in a variety of languages.
Airtable requires you to log in, but once you choose your "base" (their name for a table or board), all the documentation will directly reference that base and it's properties.
It can be easy to forget that not all developers know everything about every domain. TheEventbrite API doesn't assume you know everything and even goes so far as to explain what an API is.
Providing a user for a way to say "hey, this didn't work" makes everyone's life easier.Stripe is one of the many API providers that offer an easy way to let them know if part of their documentation was helpful.
TheTwitter API does the same on its pages. Selecting a negative response gives you a quick way to provide feedback.
Starting with a new third-party API is a big endeavor. The faster you can get it integrated, the sooner you can assess the impact it will have on your application.
Stay tuned for more articles on learning APIs in the future.
Discuss this article on Twitter and ping us @BearerSH .