Open APIs

 View Only
  • 1.  TMF622 and product order IDs

    TM Forum Member
    Posted May 14, 2020 09:14
    I'm trying to create a TMF622 product ordering API, using a Java server generated from the r19 Swagger specification.

    However, I'm confused by the behaviour of the generated server. When I try and create a product order, I'm forced by validation to specify IDs on the product order items. I find this surprising, as (unless I'm mistaken) the order items and their corresponding IDs will only be created as part of the order itself.

    Instead, what I would expect is something akin to a ProductOrderCreate object for the items, where the object doesn't have an ID. In other words,

    I would expect a ProductOrderCreate to have a list of product order items, of type ProductOrderItemCreate, and for the API to return a ProductOrder with a list of product order items of type ProductOrderItem, all of which have IDs.

    Can someone explain the intended usage here? Should I have to supply the product order IDs? Or is this validation incorrect?

    ------------------------------
    Ben R
    TDC
    ------------------------------


  • 2.  RE: TMF622 and product order IDs

    TM Forum Member
    Posted May 15, 2020 08:05
    Hi Ben,

    Use of id "wording" to identify order item is a bit confusing. Almost in all API id is provided by server.
    Here it is not this type of id.... it is an order item identifier and it is useful within the POST request message. Indeed as a product order requester there are a lot of UC where we need  to define order item relationship (product ordered in item 4 relies on product ordered on item6). This is why we have this id here, and required from POST request.

    Please note that this pattern is used in all API featuring item.

    Hope it helps

    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 3.  RE: TMF622 and product order IDs

    TM Forum Member
    Posted May 15, 2020 08:18
    Hi Ludovic,

    Almost in all API id is provided by server

    Yes, I would expect this to be the case. Perhaps I haven't made myself clear.

    If a client calls a TMF622 server to place a product order, and specifies one item on that product order, how does the client get the ID of that item?

    When placing the order for the first time, I would expect the client to provide some JSON for the item, and for the server to save it and return the newly created ID (+ other properties). But the TMF622 server generated from Swagger has validation that forces the client to provide the item ID. If the item is only created (and therefore assigned an ID) by that API call, how can the client provide the ID?

    When I mention ProductOrderCreate, this is what I'm referring to. ProductOrderCreate does not have an ID field, as the order has not yet been saved. The returned ProductOrder does have an ID. If an order has not been saved, then surely the items on that order have not been saved either. So why does ProductOrderCreate have a list of ProductOrderItem, which requires an ID to be provided, instead of e.g. ProductOrderItemCreate, with no ID field?

    Is that clearer?


    ------------------------------
    Ben R
    TDC
    ------------------------------



  • 4.  RE: TMF622 and product order IDs

    TM Forum Member
    Posted May 15, 2020 08:23
    And further to your reply, if the product order item IDs are provided by the server then at what stage does the client learn what item IDs can be added to an order? As far as I'm aware, there is no endpoint such as
    /productOrder/items
    by which we can see what item IDs are available to put on an order.

    In other words, a catalogue not of the products available, but of the order items that can be placed on an order? Or, alternatively, at what point does a client create the items to add to a product order?

    ------------------------------
    Ben R
    TDC
    ------------------------------



  • 5.  RE: TMF622 and product order IDs

    TM Forum Member
    Posted May 17, 2020 01:21
    Hi Ben

    Trying to clarify @Ludovic Robert answer.​

    When an entity has a list of sub-entities, the challenge is how to address an individual entry in that list. For example, a list of Order Items in a Product Order.
    It could be done positionally, but this is very fragile, and breaks whenever an entry needs to be removed or added.

    The pattern that we adopted is to give ids to entries. These ids are not globally unique, they must be locally unique within the list, and must be immutable once assigned.
    Hopefully you can understand from this that the consumer of the API, which is the agency that is creating the list, is therefore responsible for assigning these ids.

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



  • 6.  RE: TMF622 and product order IDs

    TM Forum Member
    Posted May 19, 2020 06:10
    Hi Jonathan,

    Thanks, this response clarifies the use case of the product order item IDs much better.

    Your answer also clarifies how those IDs are provided - "that the consumer of the API, which is the agency that is creating the list, is therefore responsible for assigning these ids". This contradicts the initial reply to this post, which was that "Almost in all API id is provided by server", but it makes much more sense because it means the validation in place when a Java server is generated from the Swagger definition (that any order item must have an ID) is satisfied.

    Thanks a lot for the explanation.


    ------------------------------
    Ben R
    TDC
    ------------------------------



  • 7.  RE: TMF622 and product order IDs

    TM Forum Member
    Posted May 19, 2020 07:30
    Thanks Jonathan and sorry Ben for the "Almost in all API id is provided by server" that bring confusion. My bad.

    Indeed in all API with item (and we have a lot: quote, all qualification, all order, etc) the item.id must be provided by the requester.

    Ludovic


    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 8.  RE: TMF622 and product order IDs

    TM Forum Member
    Posted May 19, 2020 09:44
    No need to apologise, simply a misunderstanding!

    Thanks again both.

    ------------------------------
    Ben R
    TDC
    ------------------------------



  • 9.  RE: TMF622 and product order IDs

    TM Forum Member
    Posted Oct 11, 2021 09:41
    Just to be clear in understanding,  "locally unique within the list" means each order item need to have unique id within single order. Same consumer if creating multiple orders, it need not to be unique across the orders.

    ------------------------------
    sourabh shrivastava
    Vodacom (Pty) Ltd.
    ------------------------------