10 Questions Your API Documentation Must Answer
Effective communication is the most important factor for API success. APIs do not have a user interface, so your documentation is the primary communication method for developers to interact with your API. As my API training partner Keith Casey states, “Documentation is the third user interface for APIs, and the most important”.
Your API Documentation Must Be Comprehensive
As previously discussed, our API documentation needs to move beyond API reference documentation and into all aspects of the API lifecycle. Unlike the typical SaaS-based product, however, your documentation has to target a variety of audiences, from the key decision makers to the developers ultimately integrating with it. There is no guarantee which type of audience member will encounter your API first, so your documentation effort needs to be comprehensive.
Your API Documentation Must Answer 10 Key Questions
To start your API documentation journey, it helps to focus on the questions that your audience members will ask. From the first time they encounter your API, to their initial ‘hello world app’ and beyond, the questions they will be asking are wide ranging. Being able to answer these questions will help your audience better understand what problems your API solves, engage with their first integration, and address their concerns as they consider formally adopting your API.
Question #1: Do you have an API?
Just because you live-and-breathe your API doesn’t mean others know you have one. Your corporate website and marketing materials are key entry points for those that may not know you offer an API. Be explicit about offering the API, as API-based products are still a new concept to many that will assume your product is a SaaS instead. Your documentation should call attention to your API offering, detail the problems it solves, and link to your developer portal.
Also, remember that if your developer portal is doing its job regarding search engine optimization (SEO), then non-developers may happen upon your developer portal as well. So, offer ways to get back to the overview for your product for those not as familiar with APIs. Or better yet, help them learn a little more about your product offerings and API at the same time.
Question #2: What can I do (and not do) with your API?
Once your audience begins to explore your API, they need to know what it does (and doesn’t do). Start with the problems your API aims to solve first, then move on to the features of your API that solve those problems.
By focusing on the problems and resulting solutions, you focus on the need rather than specific API endpoints. This is often accomplished through: getting started guides, integration/solution guides, and reference applications – all scattered with lots of easy-to-read code examples that can be used as a launching point once development begins.
No one will care about your beautifully designed API if they don’t know what kind of problems you can solve for them. Both decision makers and developers are trying to solve problems, not add more API integrations to their codebase. Find the problems, offer a solution, and then detail some of the nice features of your API to reinforce your API value.
Question #3: Does your API fit my company’s needs?
Once you establish the kinds of problems your API addresses, the next step is to make sure your API aligns with their specific needs and identity. Part of offering an API product is positioning your product so that it is seen as the right solution *for them*.
By offering use cases, case studies, and example applications, your product is easily aligned with the kinds of customer segments that you want to attract (and as a result you focus less on other segments). These documentation assets also builds trust as customers begin to see similar companies as themselves, causing them to picture themselves solving similar problems.
Question #4: How much does it cost?
Ultimately, price is going to become a factor. If they get this far, they have at least spent time vetting your API solution and now want to know if it will meet their budget. Be up-front with your pricing. Don’t hide your pricing behind a “Call us” link. This doesn’t mean that you can’t offer an enterprise license that requires a phone call, however.
At a minimum, provide enough pricing information to help them understand your pricing model (e.g. subscription, per transaction), subscription tiers (e.g. free, solo, team, enterprise), and what kind of support is available for each tier (e.g. forums, email, 48 hour phone, 24 hour phone, 4 hour phone). Being up-front with your pricing helps those conducting research and prevents them from removing you from their short list due to your more closed pricing approach.
Question #5: How does your API view my world?
Every API approaches a solution to a problem in a different way. The API carries with it a specific view of the world: what accounts mean, the kinds of workflows supported, and the type of data considered important.
As an example, let’s consider three popular project management APIs: Basecamp, Trello, and Rally. Each one has different views on how projects should be organized, how tasks should be created, and how they are marked as completed. Depending on how your organization prefers to manage projects will determine which solution is the best fit for you.
Therefore, it is important to document your API concepts, resources, data structures, and field types. Doing so will provide greater insight into how your API views the world and the solution to the problems your audience faces. While some view API reference documentation as the place to do that, I often recommend using Markdown or HTML-based introductory guides to capture concepts, common vocabulary, and high-level resource definitions. When sprinkled with anchor tags for deep linking, your API reference documentation can link to the specific concepts useful for the specific resource/endpoint being viewed.
Question #6: How do you secure your API?
Security of your API is important, particularly with the API security stories recently in the news. Too often, however, security is an afterthought when building APIs. Nearly every API will provide access to sensitive data, internal business systems, or share user data. Up-front security considerations prevent last-minute API design changes that make the API more difficult to use.
Your documentation should provide details on how your API handles authentication, authorization, and data security (both security in motion and security at rest). This will reenforce your product’s dedication to a professional, production quality service that will stand out against competitors.
Question #7: How long will it take to get started?
While many modern web APIs offer self-service onboarding, not every API does. If your API does offer self-service onboarding, call this out in your documentation as a benefit to getting started faster. For those that require time to go through a partnership program, include this in your documentation as well. This will ensure that the appropriate lead time is factored in prior to developers beginning the first ‘hello world’ integration.
It is also a good idea to point to example applications that have been built with a variety of programming languages, as a way to get started quickly. We recommend using Github or other public source code repository, so that developers can quickly clone your examples, configure their API key or OAuth token, and try out your API.
Question #8: Do you offer helper libraries/SDKs?
Not all developers want to code the HTTP client from scratch. This is particularly the case for developers that are new to web API integration, or for those that prefer to use their IDE and code completion to get their job done faster. If you offer SDKs, reference them in your documentation as well as in code examples. Stripe’s API documentation is a great example of integrating examples in multiple programming languages into their documentation.
Question #9: What API endpoints and event integrations does your API offer?
You will notice that we are nearing the end of our questions and only now getting to API reference documentation. Reference documentation is only one part of a complete API documentation strategy, even though it is an important one.
Your API reference documentation should list all of the available API endpoints, including details about data structures, success/error status codes returned, and request/response payload formats. Keep in mind that this reference documentation must be thorough and complete, as external developers will not have access to your source code, internal diagrams, or private documentation.
Remember that not all API integrations are one-way communication patterns. Find ways to offer a complete API conversation, allowing your API clients to make API requests when needed (“asking”) and be informed of specific server-side events (“telling”). Whether you decide to use Webhooks, Websockets, or SSE, find ways to extend your API design beyond the simple request/response design. Then, offer documentation about these integration options to show how developers can extend the typical integration scenarios with more robust options.
Question #10: Why am I getting this error code or unexpected response?
Once developers start to work with your API, they will likely encounter unexpected errors. Offer support docs with FAQs, troubleshooting guides, and developer support to help them overcome these issues and be successful. Documentation that consists of getting started guides only should be considered incomplete.
(Bonus) Question #11: What do I do if I’m not a programmer?
Not all visitors to your API product page will be developers. For those that aren’t, show them ways to use your APIs via tools such as Zapier/IFTTT, a third-party solutions marketplace, or an integration partners page. Even better, give them a demonstration of your API through a simple web or mobile app to spark their imagination and get them to take action.