helpyourneighbour/docs/api-versioning.md

# API Versioning

This project uses a simple versioning scheme for its API.

## Version Format

Versions are expressed as `vX.Y.Z` where:
- `X` is the major version (breaking changes)
- `Y` is the minor version (new features, backwards compatible)
- `Z` is the patch version (bug fixes, backwards compatible)

## Versioning Strategy

- All API endpoints are prefixed with `/api/vX/` where `X` is the major version
- The current version is `v1`
- Breaking changes will result in a new major version
- Backwards compatible changes will result in a new minor version
- Bug fixes will result in a new patch version

## Deprecation Policy

- Deprecated endpoints will be marked with a `deprecation` field in the OpenAPI spec
- A deprecation notice will be included in the response headers
- The deprecation period is 6 months
- After the deprecation period, the endpoint will be removed

## Example

```
GET /api/v1/requests
GET /api/v1/offers
GET /api/v1/deals
```

## Version History

| Version | Date       | Changes |
|---------|------------|---------|
| v1.0.0  | 2026-03-19 | Initial release |