Open APIs

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

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

Thanks Jonathan for the inputs.

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

Original Message:
Sent: Jun 16, 2020 01:41
From: Jonathan Goldberg
Subject: nomenclature of URL

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