How AI is applied across API Evangelist and APIs.io. Read my AI disclosure →
API Evangelist API Evangelist
Discovery
Learnings
Guidance
Toolbox
Alignment
API Evangelist LLC

Should my API definitions live in Git?

timeline Lifecycle & Change Updated August 12, 2026

Short answer

Yes. Git is the factory floor of API operations — definitions in version control, changes proposed through pull requests, governance running on every commit, history attributed and timestamped.

Yes, and I have believed this longer and more insistently than almost anything else in my work. Every API should begin with a repository.

The reason is that Git gives you, for free, everything an API definition needs: versioning, attributed and timestamped history, review through pull requests, branching for proposed changes, and a place for automation to hook in. An OpenAPI in Git with its full change history is the authoritative record of what the contract was at any point in time — which is exactly what you need during an incident, an audit, or a dispute with a consumer about what you promised.

It also puts governance where the work is. Linting, breaking-change detection, contract tests and artifact publishing all run on commit. Governance becomes a property of the workflow rather than a meeting.

Put the definition, the schemas, the collections, the rules, the examples and the documentation source in the repository alongside the code. What lives outside it — in a design tool, a wiki, a portal someone edits by hand — will drift, because there is no mechanism forcing it to agree with anything.

Go deeper in the guidance

This answer is distilled from the API Evangelist guidance catalog — the long-form treatment of each topic, with its own citations back into sixteen years of writing.

Read the original writing

The posts on apievangelist.com this answer is built on.