generated from coulomb/repo-seed
35 lines
1.1 KiB
Markdown
35 lines
1.1 KiB
Markdown
# API Contract Policy
|
|
|
|
The public HTTP API is currently version `0.1.0`. Until a versioned path such as
|
|
`/api/v1` is introduced, compatibility is governed by the OpenAPI contract
|
|
published at `/openapi.json` and covered by the test suite.
|
|
|
|
Agent-facing endpoints are considered stable when their path, method, tag, and
|
|
success response model appear in the OpenAPI contract snapshot test. A change to
|
|
one of those fields is allowed, but it must update the snapshot test in the same
|
|
change so the break is explicit during review.
|
|
|
|
Compatible changes include:
|
|
|
|
- adding optional request fields with defaults
|
|
- adding response fields that clients may ignore
|
|
- adding new endpoints
|
|
- adding new examples or descriptions
|
|
|
|
Breaking changes include:
|
|
|
|
- removing or renaming an endpoint
|
|
- changing an endpoint method or tag
|
|
- changing the success response model
|
|
- removing or renaming a response field
|
|
- making an optional request field required
|
|
- changing the shape of common error responses
|
|
|
|
Common application errors use:
|
|
|
|
```json
|
|
{"detail": "repository 999 was not found"}
|
|
```
|
|
|
|
Validation errors remain FastAPI's standard `422` validation response.
|