Open 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:

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

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

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

Hi,

So, if we implement a TMF API say Trouble Ticket API, the Open API version(TMF621) is 4. While implementing, we will be tailoring TMF621 specification to the needs of our organisation and keep the version as 4. In future, if we make our organisation specific backward incompatible changes, the URL need to be changed. But, as we still adhere to TMF621 - API version 4, we can't change the URL. How to address this problem.

Best Regards,

------------------------------
Kalpana HV
Colt Technology Services
------------------------------

Original Message:
Sent: Jul 01, 2020 19:58
From: Varun Nair
Subject: Version Number in TMF compliant APIs

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

Hi Kalpana,
This problem is real. There will be situations where the non backward compatible changes cannot wait till the adoption of next TMF major version.
My personal suggestion is to move to the next major version with a roadmap of upgrade, starting with organisation specific update to TMF release and publish the API in a phased manner. 
Having said that, for non backward compatible change, it is best to schedule those changes along with one of the TMF major releases & its adoption into your organisation. If that practise can be established, that would be better for release management and conformance.

------------------------------
Varun Nair
Telstra Corporation
Note: This is an opinion based on my research and not an official TMF response.
------------------------------

Original Message:
Sent: Oct 12, 2020 06:54
From: Kalpana HV
Subject: Version Number in TMF compliant APIs

Hi,

So, if we implement a TMF API say Trouble Ticket API, the Open API version(TMF621) is 4. While implementing, we will be tailoring TMF621 specification to the needs of our organisation and keep the version as 4. In future, if we make our organisation specific backward incompatible changes, the URL need to be changed. But, as we still adhere to TMF621 - API version 4, we can't change the URL. How to address this problem.

Best Regards,

------------------------------
Kalpana HV
Colt Technology Services
------------------------------


Original Message:
Sent: Jul 01, 2020 19:58
From: Varun Nair
Subject: Version Number in TMF compliant APIs

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

Hi Kalpana and Varun
Suppose you made a BC-breaking change in your implementation, it depends now if you need to support the previous behavior as well, for consumers that don't know how to deal with the change.

• If you don't have to support old consumers (all consumers are updated to support/exercise the new behavior), then you don't need to change anything, keep using v4 (say) in the uri.
• If you do have to support old consumers, it means that you must have two end-points, one for the new behavior and one for the old behavior. In this case, the old behavior endpoint would remain unchanged, with v4 in the uri. For the new behavior, you could add a minor version to the version in the uri, such as xxx/v4.1/xxx. I don't think that this would disturb the compatibility testing, although you would need to ensure that the CTK would be directed to the new endpoint. Perhaps @Henrique Rodrigues could add to this discussion.

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

Original Message:
Sent: Oct 12, 2020 20:22
From: Varun Nair
Subject: Version Number in TMF compliant APIs

Hi Kalpana,
This problem is real. There will be situations where the non backward compatible changes cannot wait till the adoption of next TMF major version.
My personal suggestion is to move to the next major version with a roadmap of upgrade, starting with organisation specific update to TMF release and publish the API in a phased manner.
Having said that, for non backward compatible change, it is best to schedule those changes along with one of the TMF major releases & its adoption into your organisation. If that practise can be established, that would be better for release management and conformance.

------------------------------
Varun Nair
Telstra Corporation
Note: This is an opinion based on my research and not an official TMF response.
------------------------------


Original Message:
Sent: Oct 12, 2020 06:54
From: Kalpana HV
Subject: Version Number in TMF compliant APIs

Hi,

So, if we implement a TMF API say Trouble Ticket API, the Open API version(TMF621) is 4. While implementing, we will be tailoring TMF621 specification to the needs of our organisation and keep the version as 4. In future, if we make our organisation specific backward incompatible changes, the URL need to be changed. But, as we still adhere to TMF621 - API version 4, we can't change the URL. How to address this problem.

Best Regards,

------------------------------
Kalpana HV
Colt Technology Services


Original Message:
Sent: Jul 01, 2020 19:58
From: Varun Nair
Subject: Version Number in TMF compliant APIs

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

Thank you @Varun Sasidharan Nair for your input.  However, business requirements would be having urgency and may not be possible to wait for a new version Open API release. 

Thank you @Jonathan Goldberg for your inputs. It gives a solution. Will wait for ​​@Henrique Rodrigues for inputs.

Best Regards,
Kalpana

------------------------------
Kalpana HV
Colt Technology Services
------------------------------

Original Message:
Sent: Oct 13, 2020 01:52
From: Jonathan Goldberg
Subject: Version Number in TMF compliant APIs

Hi Kalpana and Varun
Suppose you made a BC-breaking change in your implementation, it depends now if you need to support the previous behavior as well, for consumers that don't know how to deal with the change.

• If you don't have to support old consumers (all consumers are updated to support/exercise the new behavior), then you don't need to change anything, keep using v4 (say) in the uri.
• If you do have to support old consumers, it means that you must have two end-points, one for the new behavior and one for the old behavior. In this case, the old behavior endpoint would remain unchanged, with v4 in the uri. For the new behavior, you could add a minor version to the version in the uri, such as xxx/v4.1/xxx. I don't think that this would disturb the compatibility testing, although you would need to ensure that the CTK would be directed to the new endpoint. Perhaps @Henrique Rodrigues could add to this discussion.

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


Original Message:
Sent: Oct 12, 2020 20:22
From: Varun Nair
Subject: Version Number in TMF compliant APIs

Hi Kalpana,
This problem is real. There will be situations where the non backward compatible changes cannot wait till the adoption of next TMF major version.
My personal suggestion is to move to the next major version with a roadmap of upgrade, starting with organisation specific update to TMF release and publish the API in a phased manner.
Having said that, for non backward compatible change, it is best to schedule those changes along with one of the TMF major releases & its adoption into your organisation. If that practise can be established, that would be better for release management and conformance.

------------------------------
Varun Nair
Telstra Corporation
Note: This is an opinion based on my research and not an official TMF response.


Original Message:
Sent: Oct 12, 2020 06:54
From: Kalpana HV
Subject: Version Number in TMF compliant APIs

Hi,

So, if we implement a TMF API say Trouble Ticket API, the Open API version(TMF621) is 4. While implementing, we will be tailoring TMF621 specification to the needs of our organisation and keep the version as 4. In future, if we make our organisation specific backward incompatible changes, the URL need to be changed. But, as we still adhere to TMF621 - API version 4, we can't change the URL. How to address this problem.

Best Regards,

------------------------------
Kalpana HV
Colt Technology Services


Original Message:
Sent: Jul 01, 2020 19:58
From: Varun Nair
Subject: Version Number in TMF compliant APIs

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