A Git repository gives API artifacts a shared, versioned home. Store OpenAPI definitions there to retain their history, make changes auditable, and let teammates propose changes through pull requests (PRs). A dedicated repository also makes definitions easier to discover and helps teams reuse shared API components. section 1.5.2
Use repositories for two related purposes:
- Keep API definitions in a dedicated repository as the primary copy. Review proposed changes through PRs and run automated compliance checks before merging them. Design tools can retrieve or update these files without becoming their sole store. section 1.5.2
- Keep each environment’s declarative API gateway configuration in an environment repository. Specify the desired state in files and make updates through Git rather than the gateway UI. section 1.5.5
Gateway configuration may specify backend routing, client authentication, usage plans, rate limits, logging, and monitoring. Versioning these files lets the team collaborate on deployment settings using the same Git workflow. This is configuration as code and a GitOps approach. section 1.5.5
A repository can also be the starting point for a deployment pipeline. In continuous integration, changes are regularly integrated into its main branch; a build server then builds and tests a release candidate. Continuous delivery deploys and tests that candidate in higher environments. Repository-based checks support review, but do not replace colleagues’ judgment about an API change. section 8.3 section 1.5.2
