API Versioning

[skukx]

Is your feature request related to a problem? Please describe.

We are looking to have a native mobile app. When a mobile app is published, it will then be required for the API to always have the same response. To ensure we can have the flexibility to also update and make changes to the API, we should version it.

Describe the solution you'd like

Since the routes are already set in would probably be best to not include the version in the path but rather the Header. X-SPREE-API-VERSION: 1. If the header isn't set then it defaults to current version.

Describe alternatives you've considered

We could use versioning in the path but this would require clients to also update their paths while the env header would ensure paths could always stay the same.

Additional context

This is a tough discussion because the API typically doesn't change often. However this doesn't mean it won't evolve in the future and we can make a small change that would allow that evolution in the future.

[stem]

@epicery, we've done it with versioncake
It allows you to choose how to extract the version asked by the client :

• specific header like you propose
• the Accept header, like application/json; api_version=1
• a query param
• a body param
• a portion of the path
• etc

For what it's worth : we've decided to use the accept header as it seems to be the "HTTP way" of specifying what the client is accepting as an answer.

[kennyadsl]

Hey @skukx, thanks for opening this issue. This is something very important but does this mean that we need to release a new version of the API for any change/removal we make to the API responses (I imagine additions to the API do not require a new version)?

From what I can see in the history of changes in the /api folder, we don't have a lot of this kind of changes and I think we should avoid doing them as much as possible.

Are you seeing something in particular that could break existing client applications that we can take as an example?