ADR-008 — API Versioniong Strategy

ADR

ADR-008

Title

API Versioniong Strategy

State

Accepted

Author

klenkes74

Decision Body

klenkes74

Valid from

2025-10-03

Expires

./.

1. Context

The API is used by multiple tenants and must remain stable and extensible over time. Development is handled by a small team relying on established standards and frameworks such as Spring Boot. API versioning is required to introduce changes in a controlled manner and ensure backward compatibility.

2. Decision Drivers

3. Decision

API versioning will be implemented using media-type versioning in the HTTP header (e.g. Content-Type: application/vnd.1.3.6.1.4.1.33132.v1+json). This approach provides flexibility, allowing different versions to operate in parallel and independently of the URL structure. It is especially suitable when clients and servers require precise control over exchanged data formats.

The decision is based on the advantages described in the blog: better separation of version and resource, cleaner URLs, and the ability to manage versions via content negotiation.

The format is ´application/vnd.1.3.6.1.4.1.<PEN>+<FORMAT>.

PEN is the private enterprise number assigned to the organization by IANA. This ensures global uniqueness of the media type. We use PEN 33132 assigned to Kaiserpfalz EDV-Service.

FORMAT specifies the data format, such as json, xml, yml, or (please don. t use it) csv.

4. Consequences

  • Versioning is explicit and controlled by clients via the header.

  • URLs remain clean and unchanged, regardless of the version.

  • Frameworks and tools must explicitly support media-type versioning, which may require additional implementation effort.

  • Documentation and debugging can be more complex, as the version is not directly visible in the URL.

  • Clients must set the correct media-type to access the desired version.

5. Benefits

  • Clear separation of resource and versioning

  • Clean URLs without version information

  • Flexible and targeted version control via content negotiation

  • Good support for parallel versions and backward compatibility

6. Challenges

  • Increased implementation effort, as not all frameworks natively support media-type versioning

  • Clients must set headers correctly, which can be a source of errors

  • Version is not directly visible in the URL, reducing transparency for developers and users

7. Options

  • URL versioning (/v1/resource)

  • Header versioning (X-API-Version: 1)

  • Media-Type versioning (Content-Type: application/vnd.company.v1+json)

8. Further Reading

  • Parks, Yvonne: API Versioning: URL vs Header vs Media Type versioning, ↑PARKS01. <<<