Open APIs

 View Only
  • 1.  API Versoning

    Posted Jul 06, 2023 04:20

    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
    Atos
    ------------------------------


  • 2.  RE: API Versoning

    TM Forum Member
    Posted Jul 09, 2023 04:51

    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



    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 3.  RE: API Versoning

    Posted Jul 10, 2023 22:15

    Hi Jonathan, 

    Thanks for sharing your wealth of knowledge. I really appreciate it.



    ------------------------------
    Ayomikun Akinbobola
    Atos
    ------------------------------



  • 4.  RE: API Versoning

    TM Forum Member
    Posted Jul 10, 2023 05:50

    @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.



    ------------------------------
    Umesh Havinal
    Verizon Communications
    ------------------------------



  • 5.  RE: API Versoning

    Posted Jul 10, 2023 22:24

    Hi @Umesh Havinal Mariswamiappa 

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

    I appreciate your contribution.



    ------------------------------
    Ayomikun Akinbobola
    Atos
    ------------------------------



  • 6.  RE: API Versoning

    TM Forum Member
    Posted 29 days ago
    Hi,
     
    let me share another perspective in this topic, which is related to the interpretation of the TMF APIs and their fields and how these are implemented.
     
    Let's take a dummy, but easy to understand example:
     
    Let's assume the TMF637 Product Inventory API and that in first place the implementation has used the field 'name' of the product to carry a user friendly name for each product procured/activated for a customer. Based on this TMF API specs, the field 'name' is: "Name of the product. It could be the same as the name of the product offering".
     
    Let's also assume that at some point we realize that the product names that the consumers of this API use must match the ones in the product catalog and not those of the system storing the procured/activated products of our customers. And for some reason these are different, thus, we should switch to the 'productOffering.name' field instead of the 'name'. The API contract doesn't change, it is matter of loading the info on the proper API fields. 
     
    The question now is whether we can use a different endpoint, with a reference in the path to a different version, to support keeping both implementations in parallel. The reason: a gradual adoption of the new implementation by migrating in phases all consumers to the new one. So, for a period of time the migrated consumers will have started calling the new endpoint, while the rest consumers will be remaining calling the old endpoint.
     
    What do you think?
     
    Thank you very much


    ------------------------------
    Panagiotis Pissaris
    Vodafone Group
    ------------------------------



  • 7.  RE: API Versoning

    TM Forum Member
    Posted 26 days ago

    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



    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 8.  RE: API Versoning

    TM Forum Member
    Posted 26 days ago

    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?



    ------------------------------
    Lutz Bettge
    Deutsche Telekom AG
    ------------------------------



  • 9.  RE: API Versoning

    TM Forum Member
    Posted 23 days ago

    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.



    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 10.  RE: API Versoning

    TM Forum Member
    Posted 23 days ago

    Hi Jonathan,

    concerning the flows where href is used:

    We (Deutsche Telekom) have products from many different technology "Silos", e.g. mobile network, fixed network, Cloud products, and many more; from history, most of them have their own application stacks, e.g. each has a product inventory, and all implement the TMF637 Product Inventory API. So if we have a common TMF622 Product Ordering API (because we are also selling convergent products combining components from different "Silos") that contains references to the ordered Product instances, we not only need the ID of the Product, but also which of the different inventory APIs we have to address to retrieve the actual Product details. So in fact we need the href, or otherwise have to distinguish by e.g. Categories or something similar.



    ------------------------------
    Lutz Bettge
    Deutsche Telekom AG
    ------------------------------