---
published: true
layout: post
title: Your OpenAPI is Your API Business Requirements
date: 2025-03-17T09:00:00.000Z
tags:
  - OpenAPI
  - Requirements
  - Products
  - Business
  - Validation
image: https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/green-circuit-public-market-farmers-market.jpg
---
I spend a lot of time translating Word and PDF documents into machine-readable rules that can be used to validate an API during design, development, and build time. I’ve kind of given up on convincing people that they need to be API design-first. Not that it doesn’t matter, but I feel that it is more of a vendor concept that causes more friction than necessary, and choose to just embrace many of the concepts present in design-first, and explore what are some other ways we can make them appealing to product and engineering stakeholders. To support this, I tend to introduce business and product folks to the importance of an OpenAPI, because it provides them with a stronger vocabulary for getting what they want in the following ways.

- **Human-Readable** - A YAML OpenAPI is just a structured outline of your business requirements for an API.
- **Machine-Readable** - A JSON version of your OpenAPI can be executed and used to reflect your requirements.
- **Documented** - Your OpenAPI can be used to generate markdown and HTML documentation for stakeholders.
- **Automation** - An OpenAPI ensures your business requirements can be automated at any stage of development.
- **Validated** - Using OpenAPI ensures your business requirements can be validated at any stage of development.

I am happy for you to pay me to translate your Word and PDF documents into machine-readable OpenAPIs, but I know that once you are able to naturally articulate your business requirements using OpenAPI, you will unlock entirely new levels of putting your enterprise digital resources and capabilities to work. Your OpenAPI is your business requirements for your digital resources and capabilities. You do not have to have coding skills to use OpenAPI, and working with YAML versions of your API requirements isn’t much more than just working with structured and nested outlines in a Word or Google Doc. The only difference is that your OpenAPI can also be used to generate documentation, mock servers, code, tests, security, governance, while ensuring your business requirements are reflected throughout the life of an API.