Open APIs

Please should an API version change when a code level change is done? For example, if the Database used is changed from Postgres to Mongo DB, should the version of the API change?

Hi Ayomikun

It's generally accepted practice to use versioning for API contracts according to the semantic versioning (https://semver.org) major.minor.patch (e.g. 4.1.0)

The TMF Open APIs follow this practice. So we change major version number when making an incompatible change to the contract, for example the new version 5 APIs which are incompatible with previous versions (e.g. due to move from Swagger 2 to OAS 3, changes in RelatedParty pattern, and more).

When making a functional change to the contract that is compatible, change minor version number. And when fixing a defect, change patch version number

This has nothing to do with your internal implementation, so in your example if you can maintain the same contract (behavior/input/output) when you change your persistence later there would be no need to change API version.

Hope it helps

Please should an API version change when a code level change is done? For example, if the Database used is changed from Postgres to Mongo DB, should the version of the API change?

Please should an API version change when a code level change is done? For example, if the Database used is changed from Postgres to Mongo DB, should the version of the API change?

@Ayomikun Akinbobola  

these are based on my experiences and my views only.

there are 4 types to define API Version, follow this link - https://dev.to/akdevcraft/4-types-of-api-versioning-how-to-decide-on-next-api-version-strategy-1m0h

Ideally, if there are 10 API Consumers for any API with version (v1). API Specifications changes to include mandatory elements which impacts all 10 consumers.

then few (4)consumers are willing to accept the changes then consumers would switch to v2 when API version v2 is introduced. So the reminder 6 API consumers will still be pointing to API version v1. This reduces risks of tight coupling and inter-dependencies b/w APIs and consumers. hope this helps. let me know. thanks.

Please should an API version change when a code level change is done? For example, if the Database used is changed from Postgres to Mongo DB, should the version of the API change?

Hi @Umesh Havinal Mariswamiappa 

Absolutely, your explanation and the write-up shed more light on the context.

I appreciate your contribution.

@Ayomikun Akinbobola  

these are based on my experiences and my views only.

there are 4 types to define API Version, follow this link - https://dev.to/akdevcraft/4-types-of-api-versioning-how-to-decide-on-next-api-version-strategy-1m0h

Ideally, if there are 10 API Consumers for any API with version (v1). API Specifications changes to include mandatory elements which impacts all 10 consumers.

then few (4)consumers are willing to accept the changes then consumers would switch to v2 when API version v2 is introduced. So the reminder 6 API consumers will still be pointing to API version v1. This reduces risks of tight coupling and inter-dependencies b/w APIs and consumers. hope this helps. let me know. thanks.

Please should an API version change when a code level change is done? For example, if the Database used is changed from Postgres to Mongo DB, should the version of the API change?

Hi @Umesh Havinal Mariswamiappa 

Absolutely, your explanation and the write-up shed more light on the context.

I appreciate your contribution.

@Ayomikun Akinbobola  

these are based on my experiences and my views only.

there are 4 types to define API Version, follow this link - https://dev.to/akdevcraft/4-types-of-api-versioning-how-to-decide-on-next-api-version-strategy-1m0h

Ideally, if there are 10 API Consumers for any API with version (v1). API Specifications changes to include mandatory elements which impacts all 10 consumers.

then few (4)consumers are willing to accept the changes then consumers would switch to v2 when API version v2 is introduced. So the reminder 6 API consumers will still be pointing to API version v1. This reduces risks of tight coupling and inter-dependencies b/w APIs and consumers. hope this helps. let me know. thanks.

Please should an API version change when a code level change is done? For example, if the Database used is changed from Postgres to Mongo DB, should the version of the API change?

Hi Panagiotis

Very important discussion. When discussing backward compatibility breaks, we often tend to concentrate on the API signature (changes in input and output parameter list, changes in mandatory/optional, changes in valid value lists, etc.). It's relatively easy to identify breaking changes, and then these would have to be introduced only on a major version of the API.

However, we mustn't ignore behavioral changes, even if the signature is nominally identical. This is more difficult to nail down, but you've given an example of such a change. So now the question is - is this a breaking change or not? In your example, I would say - no. The product name is typically used for display purposes only (for humans to read); I find it very unlikely that software would make a decision based on the value of product.name. On the other hand, since humans, e.g. end customers, see (shall we say) "Telephone Service 050-5551111" on their January bill, and then "Telephone Service" on the February bill, they might get confused, resulting in increased volumes of cases in the call center.

I think you'd have to analyze each case, and bear in mind the costs of maintaining multiple endpoints, as against the benefits.

Hope it helps

Hi @Umesh Havinal Mariswamiappa 

Absolutely, your explanation and the write-up shed more light on the context.

I appreciate your contribution.

@Ayomikun Akinbobola  

these are based on my experiences and my views only.

there are 4 types to define API Version, follow this link - https://dev.to/akdevcraft/4-types-of-api-versioning-how-to-decide-on-next-api-version-strategy-1m0h

Ideally, if there are 10 API Consumers for any API with version (v1). API Specifications changes to include mandatory elements which impacts all 10 consumers.

then few (4)consumers are willing to accept the changes then consumers would switch to v2 when API version v2 is introduced. So the reminder 6 API consumers will still be pointing to API version v1. This reduces risks of tight coupling and inter-dependencies b/w APIs and consumers. hope this helps. let me know. thanks.

Please should an API version change when a code level change is done? For example, if the Database used is changed from Postgres to Mongo DB, should the version of the API change?

I fully agree, it is not only the syntax (=signature) of the API, but also its semantics. When the way fields of an API are used (e.g. in the example switching the input of Product.name from the ProductOffering.name to some other data from a backend system, this is also a major change, because consumers will probably have to adapt to cope with the change.

And it is a good idea to run the old and the new version of the API - regardless if the change is semantic or syntactic - in parallel, at least for some time, so that consumers can choose when to switch. And having the implementations of the API in different e.g. microservices (that might both access the actual data from some backend) is also a good idea, because then, when all consumers have switched, the old version can simply be switched off without having to remove old code from an otherwise common implementation.

But that opens another problem:

Assume a consumer retrieved a "change" ProductOrder from the corresponding API, and that contains the reference to the Product that is to be modified; i.e. it contains the Product's "id" and "href"; now the "href" is the URL of the Product, which contains the version of the API. So if the consumer still uses the old Product Inventory API, he needs the old version in the href, but some other consumer who has already switched to the new API version needs the new version number in href.
The provider of the ProductOrder API does not know which version of the Product Inventory API the consumer uses, so he cannot decide whcih version he should put into the href of the Product reference.

So in fact, href is a problem when we use version numbers in the URL.

Any idea how this can be solved?

Hi Panagiotis

Very important discussion. When discussing backward compatibility breaks, we often tend to concentrate on the API signature (changes in input and output parameter list, changes in mandatory/optional, changes in valid value lists, etc.). It's relatively easy to identify breaking changes, and then these would have to be introduced only on a major version of the API.

However, we mustn't ignore behavioral changes, even if the signature is nominally identical. This is more difficult to nail down, but you've given an example of such a change. So now the question is - is this a breaking change or not? In your example, I would say - no. The product name is typically used for display purposes only (for humans to read); I find it very unlikely that software would make a decision based on the value of product.name. On the other hand, since humans, e.g. end customers, see (shall we say) "Telephone Service 050-5551111" on their January bill, and then "Telephone Service" on the February bill, they might get confused, resulting in increased volumes of cases in the call center.

I think you'd have to analyze each case, and bear in mind the costs of maintaining multiple endpoints, as against the benefits.

Hope it helps

Hi @Umesh Havinal Mariswamiappa 

Absolutely, your explanation and the write-up shed more light on the context.

I appreciate your contribution.

@Ayomikun Akinbobola  

these are based on my experiences and my views only.

there are 4 types to define API Version, follow this link - https://dev.to/akdevcraft/4-types-of-api-versioning-how-to-decide-on-next-api-version-strategy-1m0h

Ideally, if there are 10 API Consumers for any API with version (v1). API Specifications changes to include mandatory elements which impacts all 10 consumers.

then few (4)consumers are willing to accept the changes then consumers would switch to v2 when API version v2 is introduced. So the reminder 6 API consumers will still be pointing to API version v1. This reduces risks of tight coupling and inter-dependencies b/w APIs and consumers. hope this helps. let me know. thanks.

Please should an API version change when a code level change is done? For example, if the Database used is changed from Postgres to Mongo DB, should the version of the API change?

Hi Lutz

Good point about the heterogenous versions across different APIs.

I would say like this: although href is an essential part of the Open API model, it is difficult to regard its content as 100% reliable. Even without the version mismatch, there is no guarantee that an href is actually executable or reachable. For example, the provider may not be aware of hops between multiple web servers, or which ports are actually used by these endpoints.

I would ask - which flows actually use the href value as-is? It's more likely that the consumer will use the id to issue a further query.

I fully agree, it is not only the syntax (=signature) of the API, but also its semantics. When the way fields of an API are used (e.g. in the example switching the input of Product.name from the ProductOffering.name to some other data from a backend system, this is also a major change, because consumers will probably have to adapt to cope with the change.

And it is a good idea to run the old and the new version of the API - regardless if the change is semantic or syntactic - in parallel, at least for some time, so that consumers can choose when to switch. And having the implementations of the API in different e.g. microservices (that might both access the actual data from some backend) is also a good idea, because then, when all consumers have switched, the old version can simply be switched off without having to remove old code from an otherwise common implementation.

But that opens another problem:

Assume a consumer retrieved a "change" ProductOrder from the corresponding API, and that contains the reference to the Product that is to be modified; i.e. it contains the Product's "id" and "href"; now the "href" is the URL of the Product, which contains the version of the API. So if the consumer still uses the old Product Inventory API, he needs the old version in the href, but some other consumer who has already switched to the new API version needs the new version number in href.
The provider of the ProductOrder API does not know which version of the Product Inventory API the consumer uses, so he cannot decide whcih version he should put into the href of the Product reference.

So in fact, href is a problem when we use version numbers in the URL.

Any idea how this can be solved?

Hi Panagiotis

Very important discussion. When discussing backward compatibility breaks, we often tend to concentrate on the API signature (changes in input and output parameter list, changes in mandatory/optional, changes in valid value lists, etc.). It's relatively easy to identify breaking changes, and then these would have to be introduced only on a major version of the API.

However, we mustn't ignore behavioral changes, even if the signature is nominally identical. This is more difficult to nail down, but you've given an example of such a change. So now the question is - is this a breaking change or not? In your example, I would say - no. The product name is typically used for display purposes only (for humans to read); I find it very unlikely that software would make a decision based on the value of product.name. On the other hand, since humans, e.g. end customers, see (shall we say) "Telephone Service 050-5551111" on their January bill, and then "Telephone Service" on the February bill, they might get confused, resulting in increased volumes of cases in the call center.

I think you'd have to analyze each case, and bear in mind the costs of maintaining multiple endpoints, as against the benefits.

Hope it helps

Hi @Umesh Havinal Mariswamiappa 

Absolutely, your explanation and the write-up shed more light on the context.

I appreciate your contribution.

@Ayomikun Akinbobola  

these are based on my experiences and my views only.

there are 4 types to define API Version, follow this link - https://dev.to/akdevcraft/4-types-of-api-versioning-how-to-decide-on-next-api-version-strategy-1m0h

Ideally, if there are 10 API Consumers for any API with version (v1). API Specifications changes to include mandatory elements which impacts all 10 consumers.

then few (4)consumers are willing to accept the changes then consumers would switch to v2 when API version v2 is introduced. So the reminder 6 API consumers will still be pointing to API version v1. This reduces risks of tight coupling and inter-dependencies b/w APIs and consumers. hope this helps. let me know. thanks.

Please should an API version change when a code level change is done? For example, if the Database used is changed from Postgres to Mongo DB, should the version of the API change?