Context and Problem Statement
We must decide on an initial version for the external API.
What is to be that initial version?
Decision Drivers
- We want API consumers (e.g. 3rd party developers) to understand the current state of the API and its architecture.
- We want an incentive (a metaphorical ‘carrot’) for 3rd party developers to upgrade to an ‘improved’ version of the API which would have a more RESTful architecture.
Decision Outcome
Chosen option: Use v0 as the Initial API Version.
This option gives us some leeway on the current architecture of the API. 3rd party developers will have an understanding that the API is usable (even if not ideal). We also have a way to incentivize developers to migrate to an improved version of the API (i.e. a future v1).
Considered Options
- Use v0 as the Initial API Version
- Use v1 as the Initial API Version
Pros and Cons of the Options
Use v0 as the Initial API Version
- Good, because it provides some leeway on the current architecture of the API (i.e. it doesn’t work in a completely RESTful manner).
- Good, because it provides a sense that the API is usable but not in an ideal state.
- Good, because it provides a ‘signal’ and incentive for developers to migrate to an improved version of the API in the future.
- Bad, because it implies that the API is in a beta state, even though we consider this to be in production.
Use v1 as the Initial API Version
- Good, because it implies that the API is ready to be used in production.
- Bad, because it gives us less leeway for changes to the API.
- Bad, because it implies that the API is in a more ideal state than it is in reality.
- Bad, because it confuses the ‘signal’ that a developer should move to an improved version in the future.