Skip to main content

45. Mandatory API Versioning

Status: Accepted Date: 2025-07-06

Context​

The Mercury system is composed of multiple services that expose APIs, such as the mercury-backend and mercury-ta service. These APIs will be consumed by various clients, including the mercury-dashboard, internal scripts, and potentially third-party integrators in the future. As the system evolves, we will inevitably need to make breaking changes to these APIs. Without a versioning strategy, any change could break existing clients, leading to unpredictable failures and a tightly-coupled system that is difficult to update.

Decision​

We will implement mandatory API versioning for all external-facing and public inter-service APIs. The versioning scheme will be URI path prefixing.

All API routes will be prefixed with a version number, for example: /api/v1/tournaments.

  • Major versions (e.g., /v1, /v2) will be introduced for any breaking change to an API contract.
  • Minor/patch changes (non-breaking additions or bug fixes) can be deployed to an existing version endpoint (e.g., to /v1).
  • When a new major version is introduced (e.g., /v2), the previous version (/v1) must be maintained for a documented deprecation period to give clients time to migrate.

This policy applies to all services that expose an HTTP API that is consumed by another service or by an external client.

Consequences​

Positive:

  • Loose Coupling: Clients can continue to use an older, stable version of the API while new versions are being developed and rolled out. This allows services to be updated independently.
  • Clear Contracts: The API version in the URI makes the contract being used by the client explicit and unambiguous.
  • Graceful Evolution: Provides a clear and predictable path for evolving the system's APIs without breaking existing integrations.
  • Easy Routing: Versioning in the URI path is easy to implement in web frameworks like NestJS and FastAPI and simplifies routing and load balancing.

Negative:

  • Code Complexity: We will need to maintain code for multiple API versions simultaneously during deprecation periods, which adds complexity.
  • Discipline Required: The development team must be disciplined about identifying breaking changes and correctly incrementing the API version.
  • Potential for Confusion: If not managed well, having many active versions could become confusing for both developers and consumers.

Mitigation:

  • Framework Support: NestJS provides built-in features for versioning APIs, which will be used to streamline the implementation and reduce boilerplate.
  • Clear Deprecation Policy: We will establish and document a clear policy for API deprecation (e.g., "old versions will be supported for at least 3 months after a new version is released"). This policy will be communicated clearly to all API consumers.
  • API Documentation: API documentation (e.g., via Swagger/OpenAPI) must be versioned alongside the API itself, making it clear to consumers which endpoints and schemas belong to which version.