Fill the Gaps between API Consumer Lifecycle Stages
What is the role of documentation in helping consumers navigate their API lifecycle?
As a consumer, you don't just want to use an API. There's a range of activities you want to participate in that involve interacting with the same API. What is the role of documentation in helping you move from one activity to the next? Can documentation do more than simply document what an API does? Read on to find out.
This article is brought to you with the help of our supporter, Scalar.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.
You have probably heard of the API lifecycle. It's a way to describe all the stages that are part of interacting with an API. The most popular lifecycle is the one that describes how producers manage an API. However, there's another one less commonly mentioned, the API consumer lifecycle.
As a consumer, all the interactions you have with an API are what you can call the API consumer lifecycle. In simple terms, the API consumer lifecycle starts at the moment someone discovers an API and ends when an integration is running and its behavior is observed. Let's look at the different stages of the API consumer lifecycle in more detail.
API discovery is where it all begins. Before consumers can use an API they need to be able to find it. The ability to make an API visible to consumers—its discoverability—is a topic vastly debated. In fact, as of today, there's no easy way for consumers to discover the best API based on their needs. This is the first step of the consumer API lifecycle.
After consumers find an API they want to see if it fits their needs. In other words, they want to evaluate it. At this stage, consumers usually try to use the API to see how difficult it is to set up an integration, how the existing operations align with their use cases, and how the API performs. Preferably, they want to run those tests against fake data and without having to do a complicated signup.
At this point, some consumers decide to move forward and invest time and resources in integrating with the API. In many cases, getting here involves a series of decisions that implicate a genuine need to use the API. What consumers now look for is an easy way to integrate the API with the programming languages and environments they already use.
After the integration is implemented consumers need to test it to see if it's working according to their expectations. Integration tests can be performed during development and also during build time right before the solution is deployed. Usually a failure in an integration test results in marking a build as failed and aborting a deployment.
If everything goes well and all the integration tests pass the solution is finally deployed. This is an important moment for consumers as they can finally see how the API integrates with the rest of their products. Their users will now be able to interact with features that consume the API so it's important to ensure it's working as desired.
Understanding the API behavior is so important that many consumers set up a monitoring solution to periodically test the integration. They often look for information related to the API response time and use observability solutions on the code that implements the integration. Their goal at this point is to find out if the integration is behaving poorly so they fix it as quickly as possible.
If this is the usual path consumers take during their interaction with an API, what can prevent them from giving up midway? Between every stage of the API consumer lifecycle, there's a moment when consumers need help moving forward. These moments are gaps that, if not properly addressed, can become hurdles hard to overcome.
One of the roles of API documentation is to fill these gaps and help consumers push their way forward. The very first difficulty happens even before the lifecycle begins. Finding the best API to use is often seen as something quite difficult. Documentation can help increase the visibility of what an API has to offer and make it easier to find.
The second gap happens between the discovery and evaluation stages. Here, the goal of documentation is to provide the easiest possible way to test the API. Consumers don't want complicated signup processes. Good documentation can guide consumers into testing the API using a sandbox even before they need to sign up.
At the third gap, consumers are ready to start integrating the API into their products. Good documentation should offer easy how-tos fit to specific use cases. Ideally, consumers should be able to grab ready-to-use code or an SDK and plug it right into their solution. Here the goal is to offer the less possible friction to a successful integration.
If the integration goes well consumers face another gap where they don't know how to create and run integration tests. The role of documentation is to offer them tutorials on how to perform the tests using their preferred programming language and framework. Documentation should be as precise as possible and address the specific needs of consumers, as opposed to being fully generic.
We're almost at the end of the API consumer lifecycle now. At this point what consumers need is guidance on how they can successfully deploy their product that now includes an integration with the API. What API documentation can provide here is concise deployment instructions and pitfalls to avoid.
After the solution is deployed and running consumers face the gap of not knowing how to retrieve observability metrics. With good documentation, they'll be able to obtain the metrics they look for with the least possible amount of effort. The documentation should point them to ways to get those metrics or, in situations where that's not possible, help them set up an observability solution.
Finally, when consumers reach the end of their lifecycle they want to know what to do next. What happens if the metrics are not as good as they should be? What happens if the solution isn't behaving as well as expected? Documentation now plays the role of providing troubleshooting instructions to common issues guiding consumers to fixing the issues they have.
As you can see, API documentation can be so much more than API documentation. If done right, documentation can be the thread connecting all the stages of the API consumer lifecycle. Documentation can play the role of providing all the information consumers need to successfully discover the best API for their needs and have it integrated into their product.