Open APIs

Expand all | Collapse all

nomenclature of URL

  • 1.  nomenclature of URL

    TM Forum Member
    Posted Jun 14, 2020 20:36

    Hi All,


    As per TMF design guidelines mentioned in section 11 called "Versioning" from TMF630_REST_API_Design_Guidelines_3.0_Part_1 _R17.5.1

    • REST APIs MUST state version with "v" following the API Name, e.g.: APIName/v1/resource.  Or  troubleTicket/v1/troubleTicket
    • The schema associated with a REST API must have its version number aligned with that of the REST API.

     

    The format for the API version number is defined as:

    {serverRoot}/{apiName}/{apiVersion}

    where

    {apiName} is the name of the API

    {apiVersion} is the version of the API (e.g. v1)

    {serverRoot} is implementation specific (e.g.: https://mycsp.com:8080 )

     

    https://mycsp.com:8080/cx/industry/tmf-api/troubleTicket/v3/troubleTicket/3180

    https://mycsp.com:8080/cx/industry/tmf-api/troubleTicket/v4/troubleTicket/3180

     

    This Above approach enables us to adhere to manage an implementation code across changing versions of TMF Open API releases.

     

    As our implementation is SaaS based, and internally we will be delivering code changes to support functional enhancements on a monthly cadence.

    Hence there is a need for us to manage an internal implementation code version across a specific version of TMF Open API release.

    For example:

    https://mycsp.com:8080/cx/industry/tmf-api/v1/troubleTicket/v3/troubleTicket/3180

    https://mycsp.com:8080/cx/industry/tmf-api/v2/troubleTicket/v3/troubleTicket/3180

    https://mycsp.com:8080/cx/industry/tmf-api/v1/troubleTicket/v4/troubleTicket/3180

    https://mycsp.com:8080/cx/industry/tmf-api/v2/troubleTicket/v4/troubleTicket/3180

      

    This Above approach enables us to adhere to manage an implementation code version both internally and across changing versions of TMF Open API releases.

     

    Please let us know if this approach is acceptable by TMF guidelines are or do we need to make any changes to the nomenclature of URL  so that we are able to manage an implementation code version both internally and across changing versions of TMF Open API releases.

    Thanks,



    ------------------------------
    Syed Javed
    Oracle Corporation
    ------------------------------


  • 2.  RE: nomenclature of URL

    TM Forum Member
    Posted Jun 16, 2020 01:41
    My understanding is that anything before the api name is the API root, and is specific to an implementation. So if you want to embed a version string within that API root, why would the standard "care".

    But practically I am not sure that this is a healthy approach, since it requires the consumers to be aware of your internal implementation versioning scheme.

    I would strongly recommend that you decouple the versioning of your software artifacts from the external 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: nomenclature of URL

    TM Forum Member
    Posted Jun 16, 2020 22:05
    Thanks Jonathan for the inputs.

    ------------------------------
    Syed Javed
    Oracle Corporation
    ------------------------------