API Documentation. Why Should I Bother?

API Documentation.?Why Should I Bother?

In our latest Tech Blog, Paul Parnell , our Lead Software Engineer shares his view on why quality Application Programming Interface (API) documentation can make a real difference.

Quality API documentation makes a difference. In software development, API documentation is often seen as an afterthought or worse, a barrier to progress. Although maintaining documentation may not be the most exciting activity, it can have big rewards in the long term.

An Application Programming Interface, more commonly known as an API, provides a set of tools to access and modify data within a system. APIs provide an agreed layer of communication between different systems to share information. Many businesses are coming to understand the value of APIs as a product; something they can offer to consumers to access their data or use their services, and can even monetise their use.

API adoption relies on usability, clarity and communication, which is why a?lot of companies are taking an API First approach. This involves designing your API contract and partaking in a review process before a line of code is written to ensure consistency?across the provided suite of?APIs.?Many?companies develop an API design guide?to keep designs consistent across teams and products. These developer-friendly APIs are predictable in?their?behaviour?and are?well documented.

The OpenAPI specification, formerly known as Swagger, defines a standard for documenting APIs. In?its?simplest guise?with no additional configuration, OpenAPI will show the request and response objects with little detail, including URLs and parameters.?For me, this doesn’t add much value.?To get the most out of API documentation, developers should provide descriptions for each body parameter in the request/response, the request headers, query parameters, path parameters, any security tokens required and also document the error responses for when something goes wrong. Describing the technical content and integration points will lead to a high degree of self-serve adoption for your API.

All APIs can fail and consumers need a consistent error format to handle these errors.?Most reasons an API will fail can be predicted in advance,?for example, a resource not being found or invalid data in the request. Providing examples of?valid requests and parameter validation?will also assist in the understanding of the API. All of this will aid?usage?of an API as everything a?consumer needs?is documented.?Developers of the API will be queried less about their API as the better the documentation, the less support consumers require. In my experience, without?good documentation, developers get frustrated and quickly look for other sources of the data they need.

If you want?adoption of?your API, then it should contain all the information that allows a consumer to get up and running quickly. Documentation of internal APIs is just as important as external APIs, and both should be treated with the same care. Design guidelines can help with this, and can start to ensure consistency?and reduce decision fatigue. A companies APIs will be built by many teams, but to a consumer this should be transparent and this is achieved by API consistency.

Quality API documentation affects the developer experience. You may have the best API that has ever been developed, but without quality documentation and communicating its existence, either your API won’t be used or may be used incorrectly.?

Spend a little time on your API documentation; your fellow developers will thank you.

If you'd like to join the team and work alongside Paul, helping us make health and wellness a way of life for everyone, check out our latest vacancies.