10 Questions Your API Documentation Must Address

The success or failure of an API often lies with its documentation. A poorly documented API that offers few answers and gives little support to the developers you wish to use it will eventually send them searching for support, and APIs, elsewhere. This article by James Higginbotham for Launch Any highlights 10 key questions from the audience’s perspective that must be answered by your API documentation.

  1. Do You Have an API?

Since API-based products are still a relatively new concept, be explicit in your mentioning that you provide an API on your corporate website and in all marketing materials.

  1. What can I do (and not do) With Your API?

Beginning with the problems your API solves, lead the reader through every capability it holds, preferably with real-world examples, to showcase exactly what it can be used for. Nobody will use your API if they don’t know what it does.

  1. Does Your API Fit my Company’s Needs?

Extrapolating on the real-world use cases with case studies and example applications is the best way to exhibit your API’s fit for a specific prospect’s needs, allowing them to picture your API supporting their product.

  1. How Much Does it Cost?

No matter how good the product is, price will often be the deciding factor for smaller businesses. Be honest about your pricing models by providing information without the reader having to contact you. If your product is good and the pricing fair, sales will come.

  1. How Does Your API View my World?

Different APIs approach problems from different angles. Not all APIs are relevant or appropriate for all issues, and so documenting your API concepts, resources, data structures and file types will allow developers to determine whether your work fits in their world.

  1. How do You Secure Your API?

API security should always be addressed from the outset of creating the API. Exhibiting this dedication to professionalism in your documentation by providing details on how your API handles authentication, authorization and data security, will help it stand out from the crowd.

  1. How Long Will it Take to Get Started?

Whether your API offers self-service onboarding or not, the details of expected lead-time for a first ‘hello world’ integration will ensure appropriate time allowances are made, reducing the potential for developer frustration.

  1. Do You Offer SDKs?

Since many developers prefer not to code the HTTP client from scratch, the fact that you offer SDKs may be a valuable selling point. Reference these in your documentation with code examples to ensure developers are aware of them.

  1. What API Endpoints and Event Integrations Does Your API Offer?

Your reference documentation should include all of the information a developer needs for every use case. This includes a list of API endpoints, with details about data structures, success and error status codes, and request/response payload formats. Any developer should be able to wield your API easily using only this documentation.

  1. Why am I Getting This Error Code or Unexpected Response?

Proper documentation goes far beyond a simple Getting Started guide. Offer real support documents with FAQs, troubleshooting guides and developer support to assist in overcoming any issues that may arise. Anything less should be considered incomplete.

Original Article

10 Questions Your API Documentation Must Answer

Martin W Brennan Martin W Brennan is a co-founder of ViewPop, the social network that puts the creation of 3D photos and videos in the hands of anyone with a smartphone. For his day job, Martin is a copywriting consultant at We Write Words, learning about the world as he writes about it.

Comments