Few things are as important to an industry as common understanding and definitions. Without knowing exactly what industry-specific terms mean, and how they apply to given situations, little discourse API development can take place. It seems strange, then, that there are still so many terms in the API space that are misunderstood or misused. Chief among these are the concepts of API Documentation, API Specification, and API Definition. In this piece, we’ll define what people mean when they use these terms, and offer some examples that represent them when we describe web APIs.

The Importance of Clarification

Half of the problem we face with these terms is that they are so often used interchangeably. For example, if one were to Google “API Documentation vs. Specification vs. Definition”, one would be hard-pressed to find cohesive definitions of the terms and what they mean to one another. Let’s begin to unravel this complicated interchangeability, and begin to form a more cohesive, relational picture of the terms.

API Documentation

Perhaps the easiest to define term of the three is API Documentation. Unlike the other two, API Documentation is relatively well understood by the API consuming and producing public at large. As its name implies, API Documentation is simply that — documentation of an API, including examples of how developers can use each function, and the constraints that the API allows.

Like any good resource, API Documentation is a layered approach to comprehensive understanding. This layered approach can be broadly summarized into three tiers — top-level, functional understanding, and technical understanding.

When we’re discussing top-level documentation, what we’re discussing is a variety of simple guides or examples as to how the API functions. These documentation points can take any variety of forms, from code examples and testing environments to screenshots.

While top-level documentation is intricately linked to functional and technical understanding, this comes much more into play when we begin to discuss API Specification and Definition, so for the time being, simply think of this tier as “basic understanding for basic functionality.”

The second tier of documentation is best considered as functional understanding. In essence, what good documentation should do at this stage is remove abstraction from the rest of the documentation. When an API consumer reads documentation, they are doing so for meaningful understanding. It shocks most people, then, when they go to read an API documentation document only to find it points them to technical terminology nested in custom formats or proprietary systems. This is not functional understanding.

Good documentation makes the foggy un-fogged. “Distributes request volume across stabilized redundant functions for a simulated looping buffer” makes no sense to the average user. “Routes high traffic to additional functions to balance resource usage” is much more effective, and builds functional knowledge of the API.

Finally, API documentation includes a good source of technical understanding. In contrast to functional understanding, this section is less concerned with functional usage of the API, and instead represents a reference from which to draw.

Function numbers, formatting examples, repository addresses, and other such data should be easily referenceable in table format, with enough details to understand without being overwhelming. The takeaway here is simple — API Documentation describes, with examples, how an API functions, and how to call those functions.

API Specification

While it is often used interchangeably with definition, API Specification is much more concerned with the overall behavior of the API, and how it links to other APIs. The two are intricately linked — you can derive documentation from specification, and vice versa, but where they diverge is a much larger data set than where they converge. API Specification, in the broadest definition, is a holistic explanation of the API.

To more specifically detail an API Specification, we can take a look at a specific example. Looking at the Swagger.io Specification, we can see a broad example of what a specification does. The swagger example combines elements of both the API Definition and the API Documentation, but for our purposes, it is a pretty decent example.

In this specification, we see a variety of functions, how they are called, and what they do. Additionally, we see a general overview of how they relate to one another, and how they can be used to more fully leverage the API.

For example, look at how Swagger defines handles specification for the Response Object session of their document:

A container for the expected responses of an operation. The container maps a HTTP response code to the expected response. It is not expected from the documentation to necessarily cover all possible HTTP response codes, since they may not be known in advance. However, it is expected from the documentation to cover a successful operation response and any known errors.

The default can be used a default response object for all HTTP codes that are not covered individually by the specification.

The Responses Object MUST contain at least one response code, and it SHOULD be the response for a successful operation call.

The specification continues on to define some general guidelines as to the expected result and formatting therein, and even goes so far as to provide an example of what the response should look like:

{
  "200": {
    "description": "a pet to be returned",
    "schema": {
      "$ref": "#/definitions/Pet"
    }
  },
  "default": {
    "description": "Unexpected error",
    "schema": {
      "$ref": "#/definitions/ErrorModel"
    }
  }
}

This is the crux of what makes specification so different from documentation. Documentation is essentially how to do something, whereas specification is essentially how something should function, and what the user should expect.

Additionally, the Specification defines the general design philosophy, either directly or intrinsically through the example structures provided for. The takeaway? API Specification details the functional and expected behavior of an API, as well as the fundamental design philosophy and supported data types.

API Definition

API Definition fills a void between the two realms of API Specification and API Documentation. Whereas API Specification is a more broad understanding of the functionality and expected results of an API, and API Documentation is a detailed discussion of how the API functions and how to utilize it, API Definition is geared toward machine-readability.

Here, we get to a crossroads — the one between machine consumption and human consumption. API Documentation appeals to human consumption — that is, API documentation is meant to be read, understood, and used by humans utilizing the API, and is thus written in a format geared towards human users.

Definition, on the other hand, is more focused on the concept of machine consumption — that is, use by machines and automated systems — than on human consumption. As API evangelist Guillame LaForge recently stated on the Nordic APIs blog:

“It’s easy to mix up the difference between the API definition format with the published API documentation. Though they are different entities, you can generate the documentation from the definition — there’s no denying the two are intimately linked. If they were completely separate, API definition formats wouldn’t even have any description tags at all, as the format would probably only be used for machine-consumption, and not for human-consumption.” – Guillame LaForge

The definition is a lot like the documentation, and in fact can often be substituted for it by experienced developers. To put it simply — API definitions define the backbone, organization, and function of an API at a base-machine readable level. API Definitions are also unique in that they provide a base starting point for derivations into other platforms — a properly formed, tagged, and thought-out Definition can form the skeleton of a multitude of derivations.

Comparing API Definition, Specification, and Documentation

The difference between API Definition, Specification, and Documentation is a two-fold difference between human and machine readability, as well as purpose and goal. API Definition is far more concerned with the general definition of an API and its structure, whereas both Specification and Documentation are concerned with informing about the API and documenting the API itself. The big difference with the latter two is that Specification is largely meant for human readability and “larger picture” understanding, while Documentation is meant for more specific, direct examples and “in the grass” details.

Hopefully, with a clearer set of definitions and a strict line dividing them, we can finally discuss API topics in a universal, clearer way. In that spirit, if you feel you have a different understanding of the terms, please comment below!