Understanding API documentation is an important skill in a developer’s toolbox. Yet, for beginners and non-technical users, it can feel like a foreign language. The good news is you can explore and use API documentation without being an advanced developer. This article will help you better understand API documentation, including how to apply different readings depending on your goal.
It’s easier to follow along with a well-organized and concrete resource, so throughout this article, we’ll primarily examine entries from Airtable’s API documentation, and more specifically, REST APIs. While you may come across other forms of API documentation, like GraphQL, we’re focusing on the type of documentation you’re more likely to encounter. First, let’s cover some basics regarding API terminology, formats, and functions.
Basic API Terms and Concepts
While you don’t have to be an expert to use API documentation, these documents generally assume knowledge of basic development terms and concepts. Fortunately, REST APIs share a standard structure and terminology, so you can use what you’ve learned elsewhere. If the terminology seems intimidating, we have a beginner-friendly article explaining API basics, as well as an API glossary you can reference for any unfamiliar terms. You’ll be up to speed in no time!
Important Formatting Concepts
A common standard for structuring REST API documentation is the OpenAPI specification. This specification offers several advantages, including the ability to generate accurate documentation and create stub code for your API. For a deeper dive, check out our guide on OpenAPI and its standards.
Comfort with the JSON data format also helps, as that’s how information is usually passed to and received from APIs. Other terms you’re likely to encounter in API documentation are:
- endpoint: a URL designated for receiving requests and sending responses
- payload: serves as the carrier of essential information within API requests and responses
- header: a set of key-value pairs that provides metadata about an HTTP request or response
- webhook: an event-driven interaction between APIs frequently used to trigger automation workflows
Common Functions
Since APIs typically rely on HTTP operations to transfer data, it’s beneficial to understand which HTTP operations are available and how they work. Frequently used operations include:
- GET: retrieves data from the server
- POST: submits data to the server
- PUT/PATCH: updates data to the server (PUT for full update, PATCH for partial update)
- DELETE: removes data from the server
In addition to operations, it’s a good idea to become familiar with common HTTP response codes and error codes in particular. These codes act as guidance for the calling client on how to proceed. Common HTTP response codes include:
- 200 OK: a successful operation
- 401 Unauthorized: the request has invalid authentication
- 403 Forbidden: the resource is forbidden to the user
- 404 Not Found: the server is unable to locate the requested resource
Another important class of operations in nearly any development environment is known as CRUD, which stands for create, read, update, and delete. If you have a basic understanding of programming, you’ll already be able to tell a large chunk of functionality will fall into one or more of the categories above. This makes CRUD operations a useful starting point for learning to read a product’s API documentation.
With the basics covered, it’s time to get into the nitty gritty of API documentation. Follow the step-by-step process below.
Step 1: Check Compatibility with Your Goals and Knowledge
You will most likely be reading API documentation to help you decide whether to use the API being described. APIs are ultimately tools, so it’s important to choose the right tool for the job you intend to do. Before committing to work with a particular API, take the time to understand both what the API does as well as what your needs are to ensure there’s a match. Reading, and more importantly, being able to see the value of the documentation, is therefore a key step.
For example, are you trying to share data, embed content like images or videos, or integrate with existing applications? You’ll want to answer these questions as early as possible in your development process to increase your chances of finding an API that aligns with your goals.
As mentioned earlier, we’re using Airtable as our example for API documentation, whose purpose is data sharing. You can use this API to integrate your data with external systems, but not, say, built-in app integration.
A deceptively simple issue is whether the documentation is written at a level that you and your team understand. Put simply, does the API documentation answer the questions you have about the API? Every piece of API documentation you encounter is going to assume some prior knowledge. Do their assumptions match your understanding? For example, the Airtable documentation tends to assume the reader is familiar with Airtable’s web interface. Aim for as close a match as possible between the level of the documentation and your capabilities.
Of course, it’s important to look for fit in other areas, such as your tech stack, support for your language of choice, and authentication standards. But if you do the hard work described previously in this section, these questions should be easy to answer by comparison.
Step 2: Explore a Path/Operation in Depth
It’s probably overkill to read an entire API reference before using it. However, exploring one method or endpoint in depth will help you get a feel for the structure of the reference and of the API itself.
CRUD operations often make great starting points for this kind of exploration. Using Airtable’s update record (the U in CRUD) endpoint as an example, you find key information explaining how to use the endpoint, such as:
- The required structure of the endpoint URL
- The difference between PATCH and PUT operations
- The types of authentication supported
- Examples of a request and a response
It can also be beneficial to explore some of the concepts you encounter in further detail. If you click on personal access token on the update record page, you’ll find more information about the kinds of authentication tokens that Airtable supports, as well as another type that’s being phased out at the time of this writing. Make a note of any questions that arise in this process.
Step 3: Read a Tutorial
Tutorials are a popular way to practice using all kinds of technical tools, and API use is no exception. Some vendors refer to their tutorials as “guides,” as Airtable (and Stoplight!) does. Many instances of API documentation contain tutorials or at least offer links to them. Shopify calls them “guides”; Slack calls them “tutorials.” Both offer prominently displayed links from their API documentation landing pages.
Describing paths/operations is often insufficient to understand how to use a real use case. In many cases, multiple APIs will need to be used to accomplish the client’s goals, and guides/tutorials provide a way to describe the overall flow of calls.
You’ll want to find a tutorial that fits with your use case. You can go as general or as specific with this as you like. An example from Airtable’s documentation that’s likely to be helpful for many users is their guide to personal access tokens. Why is it helpful? Because it covers a scenario that developers encounter frequently. A particularly notable feature of this guide is that it states early on why you might not want to use this particular guide and which one might be a better fit under those circumstances.
Once you’ve completed one tutorial, you might want to try another one to deepen your understanding of how the API works. As mentioned in the previous section, keep an eye out for potential issues that might mean the API won’t fit your needs.
Step 4: Read with Purpose and Fill in Gaps
After some reading and completing a tutorial or two, hopefully you know what endpoints you’d be working with and what questions you still have regarding the API. To fill in the gaps, reread relevant portions of the documentation and see if they answer your questions. Look at the endpoints and see if they behave as you expect. This is a good opportunity to attempt something simple, such as one or two CRUD operations, and see how your results align with your expectations.
It might even be a good idea to go back to the landing page for the API documentation and see if there are sections you haven’t read yet. One section we haven’t covered yet from Airtable’s introductory page is the Models menu. This section has a lot of useful information about Airtable’s webhooks API. Another potentially important section is the collaborations object, a key element in many Airtable API responses.
With that said, if you’re feeling overwhelmed, don’t feel like you have to explore beyond what you need. It’s absolutely fine to pace yourself. But it’s also a good idea to know where your knowledge gaps are so that you can address them when you’re ready.
What’s Next?
Once you’ve completed the steps above, you should have a better understanding of whether or not a given API — and its documentation — meets your needs, even without having a ton of development experience. If you want to move forward, the next phase involves sketching out how you think you might use this API and which endpoints you’re most likely to use.
Don’t be afraid to get your hands dirty! Stoplight has its own tool, Elements, for creating API documentation for your own products. We’d love to see what you create!
