Most development teams already use Git for application code, infrastructure, and CI/CD.
But API development is often split across several places: an OpenAPI file in a repository, tests in another tool, documentation somewhere else, and API design happening in a separate workspace.
I've been experimenting with a different approach: treating the API contract as a first-class Git artifact.
What Does Git-Native API Development Mean?
The basic idea is simple:
The OpenAPI specification lives in Git and follows the same workflow as the rest of the codebase.
Instead of:
API design → export → Git → implementation → documentation
the workflow becomes:
OpenAPI → Git branch → review → validation → implementation → CI/CD
This gives the API contract the same history, review process, and traceability as application code.
Why Put the API Contract in Git?
There are a few practical advantages.
- Pull request reviews
An API change can be reviewed directly in a pull request.
A reviewer can see when a required field was added, when a response schema changed, or when a new endpoint was introduced.
- Version history
Git provides a complete history of API changes.
You can answer questions such as:
When was this endpoint introduced?
Who changed this response?
When did this parameter become required?
Which commit introduced the breaking change?
- CI validation
Once the OpenAPI specification is in Git, CI can validate it automatically.
For example:
Pull Request
↓
OpenAPI lint
↓
Breaking-change check
↓
API tests
↓
Documentation
This makes API quality checks part of the development process rather than a manual step.
- One source of truth
The biggest benefit is avoiding multiple versions of the API contract.
The repository contains the specification that the team actually reviews and ships.
Documentation, mocks, tests, and generated clients can then be derived from that contract.
Where Does a Git-Native API Workspace Fit?
There is still a problem with a purely Git-based workflow.
Editing large OpenAPI YAML files manually isn't always the best developer experience.
This is where a git-native API workspace becomes interesting.
You can have a visual API design environment while keeping Git as the source of truth.
I've been experimenting with Apidog's Spec-first workflow for this reason.
The OpenAPI specification remains in the Git repository, while the API workspace provides a visual environment for designing and working with the specification.
The important part for me is that Git doesn't become an export destination.
It remains the source of truth.
A Workflow I Would Actually Use
For a team starting a new API, I'd consider something like:
Step 1: Create the OpenAPI contract
Start with the API design before implementation.
Step 2: Create a Git branch
git checkout -b feat/customer-api
Step 3: Update the OpenAPI specification
Define the endpoints, schemas, parameters, authentication, and responses.
Step 4: Open a pull request
Review the API contract before implementation begins.
Step 5: Run automated checks
CI can validate the OpenAPI specification and run API tests.
Step 6: Implement the API
Backend development happens against the agreed contract.
Step 7: Generate downstream artifacts
Documentation, mocks, clients, and other artifacts can be generated from the same specification.
The Interesting Part Isn't the Tool
For me, the most important concept isn't whether you use Apidog, a text editor, or another API platform.
It's where the source of truth lives.
If the API contract exists only inside a separate platform, developers may have to synchronize it with Git.
If the OpenAPI specification lives in Git, the API becomes part of the normal software development lifecycle.
That's the idea behind a git-native API workspace that I find compelling.
What About Existing APIs?
This approach doesn't have to mean redesigning an entire API.
An existing OpenAPI specification can be moved into the repository and gradually incorporated into the development workflow.
The first goal could simply be:
API specification → Git → CI validation
Then testing, documentation, mocking, and code generation can be added progressively.
Final Thought
Git transformed how we collaborate on application code.
I think API contracts deserve the same treatment.
A Git-native workflow gives API teams:
Version history
Pull request reviews
Automated validation
Easier collaboration
Reproducible changes
A clear source of truth
The interesting question for me is whether an API workspace can provide a good visual development experience without taking the API contract away from Git.
Would you adopt a git-native API workspace for your team, or do you prefer keeping API design inside a dedicated platform?
Top comments (0)