(This article originally appeared on Bearer.sh)
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.
Start with the overview
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:
- Guides: Great documentation highlights common use cases. These range from sample apps, quickstart guides, and even deep dives into more complex aspects—like authentication.
- Authentication: The authentication section is a great place to understand the authentication procedures and requirements of an API. There are three common ways of authenticating an API. Each with pros and cons. Becoming familiar with them will help you measure how long it's going to take before making your first API call.
- The Base URL: For REST APIs, this will be the foundation for all your endpoints. For GraphQL APIs, this is the root endpoint that you'll send all requests to.
- Rate Limiting: The usage guidelines for how many requests you can make in a given time, the rate limits of APIs can vary wildly. Depending on your business needs, you may need to contact the provider to request more access, but when developing it is useful to see any initial limits you may run into.
Stripe's docs are a great example of starting with the common use cases and guiding users.
Find and save the API reference
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 APIs will 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 get, list, and delete for the CalendarList instead of a list of endpoints and HTTP Verbs.
GraphQL APIs focus 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.
Take advantage of the "Explorer" or console
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.
GitHub's v4 GraphQL API Explorer uses a graphiql style UI to let you experiment with the API, and view references in one place.
Some features we love
Our favorite documentation sites put the user first.
Code Examples
Twilio takes the split approach in showing information about a resource alongside code examples in a variety of languages.
User-specific data
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.
Inclusive Language
It can be easy to forget that not all developers know everything about every domain. The Eventbrite API doesn't assume you know everything and even goes so far as to explain what an API is.
Methods of feedback
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.
The Twitter API does the same on its pages. Selecting a negative response gives you a quick way to provide feedback.
Take it from here
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.
Top comments (0)