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.
------------------------------
Original Message:
Sent: Jun 30, 2020 22:37
From: Sajitha Nair
Subject: Version Number in TMF compliant APIs
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:
- 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 - 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
------------------------------