The documentation journey starts with API Reference — Leveraging Your Developer Experience (DX)
This article is part of the Leveraging Your Developer Experience (DX) series. Find out the rest of the content here.
Writing API documentation from scratch is not really a weekend project. And top notch API documentation do take years to be built, including multiple iteration, and back and forth. But that does not mean you should spend months on your documentation before giving your consumers access to it. Here we stance for starting with the API reference.
The API Reference is a low-level but deep-dive material. It should be as descriptive as possible and as functionally agnostique as possible. API Reference is usually addressing experienced developers such as CTO or any other Decision Maker. Therefore improving it is a huge lever to your conversion rate and consequently that’s the first item you should work on.
API Reference — Cornerstone of the DX
Simple, complete and up-to-date API Reference will make or break your API operations. If developers cannot quickly get up to speed on what resources are available, and what value an API delivers, they will move on. There are just too many API resources being made available today for developers to spend too much time wading through complex or out of date reference.
Essentials that all API providers should be offering in their API reference:
- Operations List — Provide a short, concise list of all available API paths, without all the details that may complicate first impressions
- Resource Oriented Menu — The menu of your API reference must be resources oriented (presuming resources naming are enough descriptive to be understandable).
- Interactive Playground — Modern API documentation should be interactive, allowing for live calls to an API to experience the request and response of each path.
- Status / Error codes — Make sure and include all relevant status HTTP status codes and error code details as part of API documentation.
And for each resource in the menu:
- CRUD Operation List per Resource — provide a short, concise list of available API paths for this resource and filtered by method: (Create, Retrieve, Update, Delete + I advise to separate bulk or asynchronous actions).
For each operation, you must be as descriptive as possible meaning that it may contain:
- URL base — it should include the versioning of your API also.
- Path — the specific path to be added to the URL base for this operation.
- Method — the specific method for this operation among the following list according to REST: POST, GET, PUT, PATCH, DELETE.
- All Parameters (Headers, Query String, Body) — must be distinctly described and structured as much as possible following standards such as Open API Specification.
- Examples — Explain Your Request-Response Cycles. Your API users should know exactly what to expect from a successful API call. Describe the full sample response body in every supported format. Think of not only the format, like XML or JSON, but also of HTTP headers, error codes, and messages. Having too much information available for the end consumer won’t be an issue, especially when they’re trying to integrate your services into their applications.
- Try it out — another dimension for you API
For each parameter described, minimum attributes to be described are :
- Name — the field name of each parameter. ex: “contactid”.
- Description — the most important attribute functionally wise. It allow to better understand the usage of the parameter and its specific behaviour to take into account when using it.
- Schema — the most important attribute technically wise. it allow to define the type of the parameter and, if it is an object, what structure you should use.
- Deprecated — this attribute is very useful when you don’t want to deprecate a specific endpoint but want to limit the usage of your clients to specific parameters by deprecating selected ones.
Many other attributes may be used at the parameter level. For more information, have a look to this page: https://swagger.io/docs/specification/describing-parameters/
Minimum Viable Documentation
The API Reference should be sufficient enough for your first iteration of documentation.
Developers love docs following a certain standard such as OAS because that’s a guarantee of a robust, thorough framework that come with plenty of other tools that may be implemented. (We will address those tools in a future post.)
