Open APIs

Expand all | Collapse all

Version Number in TMF compliant APIs

  • 1.  Version Number in TMF compliant APIs

    TM Forum Member
    Posted Jun 30, 2020 22:37

    Hi All.

    Taking a sample from TMF 621 for Trouble Ticket API

    "href": https://mycsp.com:8080/tmf-api/troubleTicket/v4/troubleTicket/3180

     

    Per the TMF630_REST_API_Design_guidelines_Part_1_v4.0.pdf page 89, the guidelines around versioning are:

    • REST APIs MUST state version with "v" following the API Name, e.g.: APIName/v1/resource.
    • The schema associated with a REST API must have its version number aligned with that of the REST API.
    • The version number has major, minor and revision numbers. E.g. v1.0.0
    • The version number (without the revision number) is held in the URI. E.g troubleTicketManagement/v1/ticket
    • The major version number is incremented for an incompatible change.
    • The minor version number is incremented for a compatible change.

     

    I have the following questions:

    1. The version number denoted as v4 or v1.0.0 in this above examples – Is this the version of the API that a vendor implements or is this number the version of the TMF API that the vendor is complying by?

      E.g. Can a vendor comply with a TMF 621 Release 19.0.0 compliant APIs that have a URL:  http://server:port/vendor-uri/v1/ticket    or should it have v4 whihc is in the yaml  tmforum-apis/TMF621_TroubleTicket
    2. Is it mandatory to have the TMF API spec name in the URL i.e. in this example troubleTicketManagement ?
      Would a URL: http://server:port/myticketingsystem/v1/ticket be considered a compliant URL


    ------------------------------
    Sajitha Nair
    Oracle Corporation
    ------------------------------


  • 2.  RE: Version Number in TMF compliant APIs

    TM Forum Member
    Posted Jul 01, 2020 02:46
    Hi Sajitha

    The major version number in the uri must match the full version string in the swagger. Thus if you plan to implement Trouble Ticket v4.0.0 (as in the most recently published swagger for TMF621), your uri must include v4. This version (v4.0.0) is the version that you are implementing and the one you want to comply with, I don't see why there would be a difference. Note also that the Release number (e.g. 19.0.0) is really not relevant any more (apart from fitting in with the formal TMF publication structure), as our API release cycle has moved to 3-monthly sprints.

    The base path in the swagger includes the API name (for trouble ticket the published base path is /tmf-api/troubleTicket/v4), I think that the conformance kit uses this to construct full uri, but best to consult with the CTK expert @Henrique Rodrigues for confirmation.

    Hope it helps

    P.S. your Oracle colleague @Joel Burgess is very involved ​in the Open API program, so if you are not already in contact with him I advise you to reach out, as he may be able to assist with your queries.​

    ------------------------------
    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: Version Number in TMF compliant APIs

    TM Forum Member
    Posted Jul 01, 2020 19:59
    Hi Sajitha
    I suggest you align to the TMF major version convention in the URI to avoid any confusion over which version of TMF API spec you are aligned to.
    In the adoption of the TMF APIs, in many cases, an organisation has to make certain extensions specific to the organisation and life cycle manage these extensions. In these cases,  minor or patch will be used to life cycle management. It is better to ensure these open APIs aligns with TMF at a major version level. This brings a certain controlled release process, especially for non-compatible changes aligning to a major version release of TMF, but I believe it is worth aligning.

    Regarding the spec name, again it is better for organisations to align with these spec names for better conformance. These spec names define the business function which the API will perform. Aligning the business function with TMF standard notations would be good in the standardisation exercise.

    ------------------------------
    Varun Nair
    Telstra Corporation
    ------------------------------