Open APIs

Hello,

Recently I was analyzing TMF 620 and figured out that the List Categories operation does not require catalog. First I thought that the operation list all categories in all catalogs, however, in the JSON example I see only root categories as standalone array elements.  I also do see nested sub-categories in the categories elements, but I don't see them as standalone array elements.
With above in mind, am I right assuming that the operation lists only root categories from all catalogs? What's the purpose of such operation?

------------------------------
Nick Nilga
.NET Solutions Architect
Telenor Denmark
------------------------------

Hi Nick
The purpose of a catalog is to expose catalog elements (this is true for Product Catalog TMF620, and also for Service and Resource catalogs).
Specifically for product catalog, one can imagine having multiple catalogs, perhaps for different sub-markets.
The catalog elements themselves can be exposed in multiple catalogs, so I would decide at authoring time whether or not (for example) to expose a Gaming Data offering in my Corporate Services catalog (perhaps not). It is optional to have multiple catalogs.
The point is that the catalog elements themselves, including categories, are thus independent of a particular catalog. Categories are a means for structured browsing/navigation through catalog elements, and this applies independently of which catalogs expose the elements.
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.
------------------------------

Hi Johnathan,

Thanks for the explanation! I understand that categories are independent of a particular catalog, though they might be available in catalog(s). What about the subcategories? Should they appear in the response of the List Categories operation?

------------------------------
Nick Nilga
.NET Solutions Architect
Telenor Denmark
------------------------------

Original Message:
Sent: Jul 09, 2020 03:00
From: Jonathan Goldberg
Subject: TMF 620 - What categories does List Categories operation list?

Hi Nick
The purpose of a catalog is to expose catalog elements (this is true for Product Catalog TMF620, and also for Service and Resource catalogs).
Specifically for product catalog, one can imagine having multiple catalogs, perhaps for different sub-markets.
The catalog elements themselves can be exposed in multiple catalogs, so I would decide at authoring time whether or not (for example) to expose a Gaming Data offering in my Corporate Services catalog (perhaps not). It is optional to have multiple catalogs.
The point is that the catalog elements themselves, including categories, are thus independent of a particular catalog. Categories are a means for structured browsing/navigation through catalog elements, and this applies independently of which catalogs expose the elements.
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.
------------------------------

When you do a GET, irrespective of retrieve (GET by ID) or search (GET with filter), the returned entity is by default returned in full, including all the sub-entities:

• You supplied the Depth directive on the query string, in which case the entity refs will be expanded only to the specified depth
• Your implementation of the API explicitly limits the depth of expansion, and declares such in its implementation documentation.

Since Category is not a large entity, it could be argued that it would be valuable to provide full expansion by default - however this may depend on the size of the tree as constructed in a particular situation.


------------------------------
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: Jul 09, 2020 03:10
From: Mykola Nilga
Subject: TMF 620 - What categories does List Categories operation list?

Hi Johnathan,

Thanks for the explanation! I understand that categories are independent of a particular catalog, though they might be available in catalog(s). What about the subcategories? Should they appear in the response of the List Categories operation?

------------------------------
Nick Nilga
.NET Solutions Architect
Telenor Denmark
------------------------------


Original Message:
Sent: Jul 09, 2020 03:00
From: Jonathan Goldberg
Subject: TMF 620 - What categories does List Categories operation list?

Hi Nick
The purpose of a catalog is to expose catalog elements (this is true for Product Catalog TMF620, and also for Service and Resource catalogs).
Specifically for product catalog, one can imagine having multiple catalogs, perhaps for different sub-markets.
The catalog elements themselves can be exposed in multiple catalogs, so I would decide at authoring time whether or not (for example) to expose a Gaming Data offering in my Corporate Services catalog (perhaps not). It is optional to have multiple catalogs.
The point is that the catalog elements themselves, including categories, are thus independent of a particular catalog. Categories are a means for structured browsing/navigation through catalog elements, and this applies independently of which catalogs expose the elements.
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.

Hello,

I'm in doubt around this topic as well.
In the TMF620 specification conformance document, we see that "isRoot" is listed as a mandatory filter parameter to be implemented.
So, as consequence, we should be able to carry on a GET by collection with isRoot set as TRUE or FALSE meaning that we want
to list either the root categories or the nested categories

This brings the reflection that TMF expects to see nested categories outside the hierarchy as well.
Are the examples presented in the attached file correct as per TMF understanding?

Assume that the left side picture is the simple category structure and the two examples with and without using isRoot filter are being used.
Thanks and Regards,



------------------------------
Marcos Donato da Silva
Ericsson Inc.
------------------------------

Original Message:
Sent: Jul 12, 2020 03:25
From: Jonathan Goldberg
Subject: TMF 620 - What categories does List Categories operation list?

When you do a GET, irrespective of retrieve (GET by ID) or search (GET with filter), the returned entity is by default returned in full, including all the sub-entities:

• You supplied the Depth directive on the query string, in which case the entity refs will be expanded only to the specified depth
• Your implementation of the API explicitly limits the depth of expansion, and declares such in its implementation documentation.

Since Category is not a large entity, it could be argued that it would be valuable to provide full expansion by default - however this may depend on the size of the tree as constructed in a particular situation.


------------------------------
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: Jul 09, 2020 03:10
From: Mykola Nilga
Subject: TMF 620 - What categories does List Categories operation list?

Hi Johnathan,

Thanks for the explanation! I understand that categories are independent of a particular catalog, though they might be available in catalog(s). What about the subcategories? Should they appear in the response of the List Categories operation?

------------------------------
Nick Nilga
.NET Solutions Architect
Telenor Denmark


Original Message:
Sent: Jul 09, 2020 03:00
From: Jonathan Goldberg
Subject: TMF 620 - What categories does List Categories operation list?

Hi Nick
The purpose of a catalog is to expose catalog elements (this is true for Product Catalog TMF620, and also for Service and Resource catalogs).
Specifically for product catalog, one can imagine having multiple catalogs, perhaps for different sub-markets.
The catalog elements themselves can be exposed in multiple catalogs, so I would decide at authoring time whether or not (for example) to expose a Gaming Data offering in my Corporate Services catalog (perhaps not). It is optional to have multiple catalogs.
The point is that the catalog elements themselves, including categories, are thus independent of a particular catalog. Categories are a means for structured browsing/navigation through catalog elements, and this applies independently of which catalogs expose the elements.
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.

Hi Marcos
Firstly, I do urge people, when posting examples, to use real business information where possible, rather than abstract denotations (Category(1.1.2)) - it makes the use case much easier to understand. So if you can do this without violating your organization's IP policies, great.
I think your illustration of the expected API behavior is correct, unless the specific implementation decides to impose a default value for isRoot if it was not supplied in the filter on the query string. Although as a general rule I don't think we specified in Open API default values for query parameters when not supplied, perhaps there is a case for doing this for boolean parameters. I can bring it to the attention of the team.
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: Sep 09, 2020 09:13
From: Marcos Donato da Silva
Subject: TMF 620 - What categories does List Categories operation list?

Hello,

I'm in doubt around this topic as well.
In the TMF620 specification conformance document, we see that "isRoot" is listed as a mandatory filter parameter to be implemented.
So, as consequence, we should be able to carry on a GET by collection with isRoot set as TRUE or FALSE meaning that we want
to list either the root categories or the nested categories

This brings the reflection that TMF expects to see nested categories outside the hierarchy as well.
Are the examples presented in the attached file correct as per TMF understanding?

Assume that the left side picture is the simple category structure and the two examples with and without using isRoot filter are being used.
Thanks and Regards,



------------------------------
Marcos Donato da Silva
Ericsson Inc.
------------------------------


Original Message:
Sent: Jul 12, 2020 03:25
From: Jonathan Goldberg
Subject: TMF 620 - What categories does List Categories operation list?

When you do a GET, irrespective of retrieve (GET by ID) or search (GET with filter), the returned entity is by default returned in full, including all the sub-entities:

• You supplied the Depth directive on the query string, in which case the entity refs will be expanded only to the specified depth
• Your implementation of the API explicitly limits the depth of expansion, and declares such in its implementation documentation.

Since Category is not a large entity, it could be argued that it would be valuable to provide full expansion by default - however this may depend on the size of the tree as constructed in a particular situation.


------------------------------
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: Jul 09, 2020 03:10
From: Mykola Nilga
Subject: TMF 620 - What categories does List Categories operation list?

Hi Johnathan,

Thanks for the explanation! I understand that categories are independent of a particular catalog, though they might be available in catalog(s). What about the subcategories? Should they appear in the response of the List Categories operation?

------------------------------
Nick Nilga
.NET Solutions Architect
Telenor Denmark


Original Message:
Sent: Jul 09, 2020 03:00
From: Jonathan Goldberg
Subject: TMF 620 - What categories does List Categories operation list?

Hi Nick
The purpose of a catalog is to expose catalog elements (this is true for Product Catalog TMF620, and also for Service and Resource catalogs).
Specifically for product catalog, one can imagine having multiple catalogs, perhaps for different sub-markets.
The catalog elements themselves can be exposed in multiple catalogs, so I would decide at authoring time whether or not (for example) to expose a Gaming Data offering in my Corporate Services catalog (perhaps not). It is optional to have multiple catalogs.
The point is that the catalog elements themselves, including categories, are thus independent of a particular catalog. Categories are a means for structured browsing/navigation through catalog elements, and this applies independently of which catalogs expose the elements.
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.