[📑 Docs]: Describe different versioning strategies

[jonaslagoni]

What Dev Docs changes are you proposing?

Versioning can be hard, and with no clear information on the site about the different approaches, it is hard to figure out which one to choose.

We can learn a lot from existing versioning strategies in OpenAPI, however, as someone coming into AsyncAPI, it can be difficult to figure out how to find the solution that fits your use case.

One thing to remember is that the version strategy can be restricted by individual protocols, libraries, platforms, etc that are in use. So when we describe them we need to remember no one strategy is a silver bullet, and it should be written accordingly.

Related resources:

• https://apisyouwonthate.com/blog/api-versioning-has-no-right-way
• https://cloud.google.com/endpoints/docs/openapi/versioning-an-api
• https://www.mnot.net/blog/2012/12/04/api-evolution.html
• https://calver.org/
• https://semver.org/
• https://yonatankra.com/handling-different-kafka-message-versions/

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

[quetzalliwrites]

Hey @jonaslagoni, this sounds like a great new doc for sure! I can see the huge value of explaining how different versioning strategies work within AsyncAPI.

Are you willing to provide background context that is specific to AsyncAPI? Otherwise, it will be hard to get a doc started that is tailored only for our spec.

[jonaslagoni]

Are you willing to provide background context that is specific to AsyncAPI? Otherwise, it will be hard to get a doc started that is tailored only for our spec.

I can kickstart it, but there are many questions to answer, so I am probably not formulating myself correctly or including everything. So solving this will require some research and thinking 😄

I think we can split it up into standard versioning strategies and then for each protocol we can deep dive a bit as to what setup might benefit the user.

An important note is that it's not only important you CAN version stuff you also need the HOW, which depends on many factors such as where the AsyncAPI documents are located, what tooling is available, etc. Basically governance 😅 Which is a whole other subject that needs to be covered I think.

And remember, there are no silver bullet here 😆

Standard versioning strategies

• Versioning the document itself. As I can figure out Semver and Calver are the most widely used here.
  • Semver requires you to take into account what is breaking and what is not to determine the major version.
    • Our Diff library can help out automate, enforce and validate that you don't accidentally make a major version change when you intended a minor.
    • Bump has some tools to help here as well: https://bump.sh/blog/api-design-first-with-bump-diff
  • Calver forces each change to be a breaking version. Don't have much experience here so can't provide much help here. Each of these strategies is just standard behavior, each protocol, tooling, and desire create pros/cons for each approach.
• Use resource versioning alongside versioning the document itself
  • Either through the topic: https://apisyouwonthate.com/blog/api-versioning-has-no-right-way#resource-versioning-uri-based
    • There are different ways to achieve this with parameters, hardcoding, etc.
  • Or through headers: https://apisyouwonthate.com/blog/api-versioning-has-no-right-way#resource-versioning-mime-based
    • I am not sure all protocols support headers, so that might be restricted as to when it makes sense to use.
  • Version in query parameters i.e. /my/path?version=1
  • Versioning the payload schemas
    • I could not find any resources for this, but in some protocols, especially WS I think it might make sense to have a payload as

type: object
properties:
  version:
    enum: ['v1', 'v2', 'v3']
  v1: 
    $ref: '#/components/schemas/V1_User'
  v2: 
    $ref: '#/components/schemas/V2_User'
  v3: 
    $ref: '#/components/schemas/V3_User'
required:
  - version

• Versioning the server/protocol endpoint so you have v1.mybroker.com.
  • In complex broker setups, that might be weird and complex to achieve.

Protocol specific

I can only give you an example of the NATS protocol how it might affect your decision.

NATS have the possibility to granularly fine-tune access control on subjects through permission maps.

If I want to utilize this to control who and when new versions are made available in the broker I need to include topic versioning.

@alequetzalli not sure if this is what you where looking for?

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart: