Your API specification IS NOT your API documentation
Introduction
Everyday integration and API architects and developers are faced with challenges around articulating and understanding the true nature and real meaning of APIs and even more, the nuances and differences between API specification and API documentation.
These 2 aspects of APIs are often and wrongly contextualized, used and interchanged as if they were the same, when in fact these are completely separate aspects of exposing and consuming APIs, which usually leads to inevitable “WAFAQ” (Wrongly Answered Frequently Asked Questions)…
Usually the response is a reluctant “YES”, followed by a few questions regarding such as:
- How to start consuming the API?
- What are the limitations on using the API?
- What security mechanism are supported by the API?
- What business functions are provided by the API?
- And so on…
In other words, and as people say “you can’t compare apples and oranges”, because they are simply different. Same principle is in the world of APIs, which is the focus of this blog post elaborating on the fact that…
Your API specification IS NOT your API documentation
Before moving on to the topic in discussion in this post, to avoid any misunderstandings, the reference to API documentation discussed in this article means documentation to be used by external parties (aka API consumers), and should not be confused with API technical specification and documentation, which has a similar name, but totally different meaning and purpose, as it describes both functional and non-functional requirements, determining how the inner working of the APIs should operate, and having the API development team as the audience.
API Definitions and Principles
An API (acronym for Application Programming Interface), is an intermediary software, clearly defined functionality and boundaries that allows consumers or users of the API to programmatically access services functions on another application or a database.
These boundaries and functionality are based on a few definitions and principles, some of which are being highlighted below.
Purpose
An API must be designed and built with a purpose, exposing an specific set of functionality bound to a context on which it operates, catering for the specific needs of its consumers.
Abstraction
APIs purposedly abstract the implementation and all the inner complexities of those systems, and database, thus solely exposing functionality needed and that matters for external consumers. This way, API consumers implement functionality to use the API based on a a set of agreed terms of inputs and outputs also known as contract or interface.
Interface
Consumers interact with APIs through a common and well-defined interface, that is usually specified and agreed upon between the party exposing the API and the party consuming the API, guaranteeing purpose and abstraction.
Composition
Other than catering for common protocols and communication styles, composition is one of the major advantages of adopting APIs, as they facilitate the creation of building blocks for the development of new interactions with humans, other applications or smart devices.
Specification
Are the means of technically describing the functionality of an API and how to build and use it, including input and parameters, error codes, etc.
Documentation
Last, but not least in this list containing some API definitions and principles, documentation is the driving force that enables discovery, adoption and consumption of APIs. This is where in a more high-level or business level API providers will document how the API can be consumed and combined, providing meaning and value add.
An important note:
The term API documentation that is used and referred to throughout this article refers to documentation intending at easing the discovery and consumption of APIs, therefore having API consumers as the audience, and as such, does not describe the inner workings of the API as in a Technical API documentation and specification, which is intended at describing functional and non-functional requirements to API architects and API developers, therefore, even though these two have a similar name, their context, intention, and purpose are different and should not be confused. Except for this note, a Technical API documentation and specification will not be covered or mentioned in this article.
History of API Specifications and Documentation
Over the years, community and consortiums responsible have taken the responsibility of standardizing how APIs are specified and documented.
From 2011, with the release of Open API Specification (OAS), also known as Swagger, and the popularity of Swagger UI, and later coming RAML and more recently AsyncAPI, attempts of bringing both documentation and specifications together was made, which lead to a number of API providers to assume that their API specification is their API documentation, when they are in fact different and complement each other.
Characteristics of API Specifications
API specifications as we all know are designed in different formats or a combination of formats, ranging from XML and later coming JSON and YAML.
- They pretty much describe resources, data types, traits and other technical aspects
- Including requests and responses, headers, status codes, etc.
- They are therefore like contract terms between APIs and consumers, but they won’t tell you how to use or what to do with them
THEREFORE
- They are unfriendly and noncomprehensive for those that are not quite technical, who will possible consume them using low-code tools and platforms
- API specifications won’t give you scenarios or uses cases where that API applies or belongs as part of a process
- So they won’t have any particularly relevant details regarding business meaning or outcome
- They are agnostic to technology, platform and tools, therefore they will not have any code snippets or mocking capability by themselves
- Last but not least, they certainly will not describe what to do when an error occurs — Who to speak to? How do I log a ticket? What is the version history?
