API Versioning Recommendations in Docs

[jspetrak]

Decide on API Versioning

Decision Tree

Versioning of resource or suite?

How/where do we version (path, header,...)?`

Which kind of header versioning

HTTP version (RFC 4229): version: 2.0

Media Type Profile (RFC 6906) Accept: application/json; profile="https://osdm.io/2.0"

Media Type Version Accept: application/vnd.osdm+json;version=2.0

Backward compatibility and semantic versions

Many questions: Form a small group of experts

Decisions:

We must adhere to semantic versioning OSDM 2.1 will be OSDM 3.0 as we have breaking changes

[jspetrak]

The header versioning is anticipated in favor of URL versioning.

Recommendation should be documented at osdm.io.

[jspetrak]

Vendor-specific media types can be registered with IANA in order to be recognized (prefix vnd. ) Otherwise they should be prefixed with x.

[jspetrak]

• We have agreement on using the Zalando proposal.
• OSDM Media Type should be registered with IANA. (David Sarfatti to be the contact person)
• Document properly at osdm.io once the Media Type is secured.

[jspetrak]

Josef to draft documentation for 24.11.

[jspetrak]

@jspetrak Check if versioning by profile in header is already documented. Document if not.

Mime type to be introduced in 4.0 as breaking change.

[CGantert345]

The OSDM media type has been accepted by IANA:

https://www.iana.org/assignments/media-types/media-types.xhtml https://www.iana.org/assignments/media-types/application/vnd.uic.osdm+json

vnd.uic.osdm+json