Open APIs

Hi there,

I've noticed in the early preview of TMF679 ProductOfferingQualification APIs that a Check- and QueryProductOfferingQualificationItem can reference 0 to 1 PromotionRef resources and I wanted to doublecheck with you the idea behind it. Is my assumption correct that for
queryProductOfferingQualification, the promotionRef references an applicable promotion and for checkProductOfferingQualification, the client can validate the commercial eligibility including the validation of the referenced promotion?

If so: is there a chance to move from a 0 to 1 cardinality to an array of promotionRefs? In our use cases, we would have to deal with several promotions applied at the same time.

Many thanks in advance

------------------------------
Patrick Brantner
IBM Corporation
------------------------------

Hi,

I'm still a Padawan in TMF APIs but my understanding is that (in TMF API language), an entity that is suffixed with REF is basically a "join" to another entity where you will get the full details of the REFerenced object. Many TMF APIs use this syntax for reference.

how it (should) works:
The QueryProductOfferingQualificationItem entity would contain a list of 0...n  qualifiedproductofferingitems
Each item is either a product offering or a promotion (never both at the same time) This is why the cardinality is 0,1 (it's like a join in SQL language)

In the API response, each item is representated by an Id, a name, HREF and @type
But that's possibly not enough for your API consumer. So if the consumer want to know more (e.g. from date, prices etc) , you need to query the related entity. that's what productofferingREF or a promotionREF are.

in the API doc (V5) , go to page 29 and you will see an example with 6 qualifiedproductofferingitems.
you will see that all 6 items REFer to the product offering entity, e.g. the first 2 items from page 29:

"qualifiedProductOfferingItem": [
     {
     "@type": "QualifiedProductOfferingItem",
     "productOffering": {
           "id": "DPI89",
           "name": "European Data Plan - 20 GB",
           "href": "https://host:port/productCatalogManagement/v5/productOffering/DPI89",
           "@type": "ProductOfferingRef"
           },
           "id": "1"
     },
     {
     "@type": "QualifiedProductOfferingItem",
     "productOffering": {
           "id": "DPI90",
           "name": "European Data Plan - 50 GB",
           "href": "https://host:port/productCatalogManagement/v5/productOffering/DPI90",
           "@type": "ProductOfferingRef"
           },
           "id": "2"
     },

etc​

you will notice that each item provides:

• the API URL of the related entity (in "href")
• the meaning of the related entity (in "@type"), this would either be "ProductOfferingRef or "PromotionRef")

Ideally, the API documentation could include a few promotions in thequalifiedproductofferingitems usage sample to show a more complete picture.

sorry if I don't use the appropriate API jargon so I hope I made myself clear! @Jonathan Goldberg will surely explain it in a better English.

PS: maybe the final API specification will have the REForValue pattern!. Just teasing.​

------------------------------
Kind regards,

Matthieu Hattab
Lyse Platform
------------------------------

Hi,

I am aware of the Ref/Value pattern - sorry if my first post was a bit misleading. However I think you also answered my actual question on the semantics of the ProductOfferingRef/PromotionRefs and how multiple instances of it can be combined. So thank you very much for all the details and explanations!

I however think the QueryProductOfferingQualificationItem misses the hierarchy in the PDF/OpenApi definition :)

------------------------------
Patrick Brantner
IBM Corporation
------------------------------

Original Message:
Sent: Nov 22, 2022 11:12
From: Matthieu Hattab
Subject: TMF679v5 including PromotionRef

Hi,

I'm still a Padawan in TMF APIs but my understanding is that (in TMF API language), an entity that is suffixed with REF is basically a "join" to another entity where you will get the full details of the REFerenced object. Many TMF APIs use this syntax for reference.

how it (should) works:
The QueryProductOfferingQualificationItem entity would contain a list of 0...n  qualifiedproductofferingitems
Each item is either a product offering or a promotion (never both at the same time) This is why the cardinality is 0,1 (it's like a join in SQL language)

In the API response, each item is representated by an Id, a name, HREF and @type
But that's possibly not enough for your API consumer. So if the consumer want to know more (e.g. from date, prices etc) , you need to query the related entity. that's what productofferingREF or a promotionREF are.

in the API doc (V5) , go to page 29 and you will see an example with 6 qualifiedproductofferingitems.
you will see that all 6 items REFer to the product offering entity, e.g. the first 2 items from page 29:

"qualifiedProductOfferingItem": [
     {
     "@type": "QualifiedProductOfferingItem",
     "productOffering": {
           "id": "DPI89",
           "name": "European Data Plan - 20 GB",
           "href": "https://host:port/productCatalogManagement/v5/productOffering/DPI89",
           "@type": "ProductOfferingRef"
           },
           "id": "1"
     },
     {
     "@type": "QualifiedProductOfferingItem",
     "productOffering": {
           "id": "DPI90",
           "name": "European Data Plan - 50 GB",
           "href": "https://host:port/productCatalogManagement/v5/productOffering/DPI90",
           "@type": "ProductOfferingRef"
           },
           "id": "2"
     },

etc​

you will notice that each item provides:

• the API URL of the related entity (in "href")
• the meaning of the related entity (in "@type"), this would either be "ProductOfferingRef or "PromotionRef")

Ideally, the API documentation could include a few promotions in thequalifiedproductofferingitems usage sample to show a more complete picture.

sorry if I don't use the appropriate API jargon so I hope I made myself clear! @Jonathan Goldberg will surely explain it in a better English.

PS: maybe the final API specification will have the REForValue pattern!. Just teasing.​

------------------------------
Kind regards,

Matthieu Hattab
Lyse Platform
------------------------------