---
published: true
layout: post
title: The Politics of the API Specification
tags:
  - OpenAPI
  - JSON Schema
  - APIs.json
  - Specifications
image: >-
  https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/eugenics-turing-front-view.jpg
---
The importance of open-source API specifications isn't always easy to see as teams work to complete their sprints, and ensuring their Jira tickets meet the definition of done. The value of the naming, order, and completeness or incompleteness of the machine-readable artifact used to describe the surface area of HTTP digital resources and capabilities matter a lot to both API producers, consumers, service providers, and stewards of these standards. Portals, documentation, sandbox, and SDKs are the obvious place to begin when looking for the politics of API specs, but here are a few of the areas it tends to accumulate.

- **Competing Specs** - Every year or two you will see new specifications emerge trying to unseat OpenAPI due to its real and perceived shortcomings.
- **Derivative Specs** - If you can’t replace a spec, then you work to extract mindshare and its value with related specs like Postman or Bruno collections.
- **Import / Export** - The VC playbook 101 for their startups is that you import OpenAPI, but you work to limit the export of OpenAPI especially w/ extensions.
- **Completeness** - Who is incentivized to produce a complete artifact that accurately represents what is possible with an API when defined as an specification.
- **Learning** - When someone or a group is resistant to learning an API specification to understand what it does and how it is applied as part of operations.
- **Education** - The absence of specification education is another telling sign of the politics that exist which keep people from learning about specifications.

People tend to see politics as something unpleasant and front and center, which it can be. However, the politics of the API specifications tends to happen via services, tooling, source control, and pipelines, as specifications are applied (or not). The politics of API specifications tends to exist in the abstractions and transformations of the specification to meet the needs of a particular company, organizations, and institution. The politics of API specifications is very present in the entropy of our digital operations and team engagement. Specification politics is what contributes to the chaos, sprawl, and it being so difficult to find the API signal in the noise with a single API, but also with APIs at scale, and the operations around them.