Open APIs

Expand all | Collapse all

Documentation or Swagger File

  • 1.  Documentation or Swagger File

    TM Forum Member
    Posted Jan 16, 2019 04:55
    Dear Forum,

    Following the swagger file for "TMF620_Product_Catalog_Management_API_REST_Specification_R17.5.0 " document, i've realized the productOffering model included on  "GET /productOffering/{id}" interface has a list of taxes inside of productOfferingPrice but this tax list is not represented in the API specification document.
    What should i Ifollow? The documentation or the swagger file?
    I took the documentation and swagger file from this link Open API Table - TM Forum Ecosystem API Portal - TM Forum Confluence

    Thanks in advance
    Best Regards,



    ------------------------------
    António Ribeiro
    Celfocus
    ------------------------------


  • 2.  RE: Documentation or Swagger File

    Posted Jan 17, 2019 07:40
      |   view attached
    Hi António

    You can see that regular Swagger from GitHub https://github.com/tmforum-apis/TMF620_ProductCatalog is uploaded in March 2018, and "TMF620_Product_Catalog_Management_API_REST_Specification_R17.5.0"  created in January 2018. So, Swagger file is more relevant in my view.

    Document ProductOfferingPrice contains  a "Price" object, which consist of taxIncludedAmount, dutyFreeAmount, taxRate and percentage attributes (See the screenshot in attachments).

    Swagger file ProductOfferingPrice has a "tax" collection.
    "tax": {
                        "type": "array", 
                        "items": {
                            "$ref": "#/definitions/Tax"
                        }
                    }
    				
    	"Tax": {
                "type": "object", 
                "description": "An amount of money levied on the price of a Product by a legislative body.", 
                "properties": {
                    "taxAmount": {
                        "$ref": "#/definitions/Money", 
                        "description": "tax amount"
                    }, 
                    "taxCategory": {
                        "$ref": "#/definitions/Money", 
                        "description": "A categorization of the tax rate."
                    }, 
                    "taxRate": {
                        "type": "number", 
                        "format": "float", 
                        "description": "Tax rate"
                    }
                }​
    And ProductOfferingPrice has no more "Price" object.

    I think you should follow the Swagger file. Also I create Swagger version control in my project to help track changes in Swaggers.

    ------------------------------
    Artyom Valeev
    Mobile TeleSystems OJSC
    ------------------------------



  • 3.  RE: Documentation or Swagger File

    TM Forum Member
    Posted Jan 20, 2019 14:07
    Hi all
    We are currently going through a process of rationalization that will eliminate discrepancies between the specification document and the swagger files. Both artifacts will be generated from the same underlying set of schemas for the Open API entities, and a control file for each API that defines the operations and notifications to be supported per entity. For release 18.5 this process covers eight APIs mainly in the Service domain, but we can expect it to extend to the other APIs - including product catalog - in coming releases (19, 19.5) according to priorities to be set by the program leads.
    In addition, an enhancement was made in the SID in release 18.5 to more correctly represent taxation, this enhanced model should find its way into the Product Catalog API in the coming releases.

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    ------------------------------



  • 4.  RE: Documentation or Swagger File

    TM Forum Member
    Posted Jan 22, 2019 05:47

    Hello, All

    Looking at the swagger file

    https://github.com/tmforum-apis/TMF620_ProductCatalog/blob/master/TMF620_Product_Catalog_Management.regular.swagger.json

    I can see that PriceAlteration object still contains the Price structure. PriceAlteration itself is not mentioned as sub-resource of ProductOfferingPrice. That looks incorrect.

    My guess the swagger files should be verified as well as API document.

    Regards



    ------------------------------
    Viacheslav Zimovets
    Netcracker Technology
    ------------------------------



  • 5.  RE: Documentation or Swagger File

    TM Forum Member
    Posted Jan 23, 2019 13:35
    Hi - some additional information that will be useful. In the previous (release 14.5) product catalog API, ProductOfferingPrice was a sub-entity, embedded within ProductOffering (and including its own sub-entities Price and PriceAlteration). In the current (release 17.5) API, a revised stand-alone ProductOfferingPrice entity was introduced, without the Price and PriceAlteration sub-entities. However so as to make the change gradual, the embedded ProductOfferingPrice was kept as well. It is possible that this has caused confusion. In any case the plan is to remove the embedded POP in release 19, as per the JIRA issue https://projects.tmforum.org/jira/browse/AP-1153.
    Hope it helps

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    ------------------------------



  • 6.  RE: Documentation or Swagger File

    TM Forum Member
    Posted Jan 25, 2019 06:31
    Hi,
    Based on your previous answer, we must follow the productOfferingPrice as a stand-alnoe entity. Even so, i would like to ask you the following questions:
    1. how can you model the following price with loyalty points: for instance IPHONE X 300€ + 1000points
    2. How does popRelationship works? Does popRelationship is list of product offering prices?

    Thanks in advance
    Best Regards,
    António Ribeiro

    ------------------------------
    António Ribeiro
    Celfocus
    ------------------------------