Open APIs

Expand all | Collapse all

Pagination: offset and limit

  • 1.  Pagination: offset and limit

    Posted Nov 21, 2018 10:06
    Hello dears,
    i am new to TMF APIs and new to this discussion group,
    so sorry i my questions seems silly :)

    1. How can i include Pagination: an offset and a limit to the queries; the result will be from record at 'offset' to record at 'offset+limit'?

    2. In product ordering : I have an order with many order items, the order items don't have the same start-time (aka activation date) how can i include that parameter ?

    3. API for Bill Creation: Does it exist an API to create dynamically a bill (not using order apis) ? (Call the API and parameters will be the Bill details)

    4. Payment Plan: Is it possible to supply the payment plan dynamically ? (to give the payment plan agreed with the customer when making the order)

    Any help/hint/link will be highly appreciated
    Thank you very much
    Best regard

    ------------------------------
    Ibrahima Gaye
    ZTE Corporation
    ------------------------------


  • 2.  RE: Pagination: offset and limit

    TM Forum Member
    Posted Nov 22, 2018 06:14
    Hi Ibrahima,

    1. Pagination and other generic concepts used in all API are described in TMF630. You will find pagination specifically in chapter 4.01 of Part 1.

    2. A productOrder has only one "expectedStartDate" that applies to all the orderItems. You can however add an appointment to each orderItem so that they will be activated at the moment of appointment. 
    If the solution with appointments is too involved you could also split the order and group orderItems per expectedStartDate.

    3. TMF678 should handle your bill creation needs.

    4. TMF666 models PartyAccount with Payment Plans. It is to you to dynamically add this into your Order Capture flow.






  • 3.  RE: Pagination: offset and limit

    TM Forum Member
    Posted Nov 22, 2018 06:15
    Pagination is done using RFC7233 range request HTTP headers where the unit is "items".

    This is described in Design Guidelines for REST APIs - Part 1 in the section Query Resources with Attribute Filtering and Iterators.

    ------------------------------
    Vance Shipley
    SigScale Global Inc.
    ------------------------------



  • 4.  RE: Pagination: offset and limit

    TM Forum Member
    Posted Nov 24, 2018 16:17
    Regarding the order item date, I am not so sure that the Appointment route is appropriate - not all order items need appointments. Better would be to add an explicit attribute in OrderItem as an extension, to capture the variation in dates across order item. Adding @Ludovic Robert, the lead for Product Order API.​

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



  • 5.  RE: Pagination: offset and limit

    TM Forum Member
    Posted Nov 26, 2018 04:09
    Hello

    About order date I will be aligned with @Jonathan Goldberg and I will suggest to leverage open API extension pattern at order item level to add dates. All the dates are defined at header level but it could be perfectly valid for some of them to be defined as well at item level (requestedstartDate, requestedCompletionDate, expectedCompletionDate, completionDate).

    Best regards

    Ludovic​

    ------------------------------
    Ludovic Robert
    Orange
    ------------------------------



  • 6.  RE: Pagination: offset and limit

    TM Forum Member
    Posted 15 days ago
    Hello,
    I was checking the TMF630 around pagination and, I'm in doubt around these sentences:
    1) Pagination is mandatory  - Assumed answer is yes.
    2) Pagination can be done with offset and limit or, must be done with offset and limit - Assumed answer is CAN.
    3) Pagination can be done with content range as the pagination solution to the offset and limit - Assumed answer is YES.

    Summarizing: Given that pagination is mandatory, I can choose between the "offset" or "content range" solution for pagination.
    Is this correct?

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



  • 7.  RE: Pagination: offset and limit

    TM Forum Member
    Posted 15 days ago
    Hi,

    1) Seems the current guideline is enforcing supporting pagination. I think this should be a challenged assertion, as pagination, like support for any pattern, is really to be implemented if there is some effective usage planned for it. This should be part of setting the design, always, but not enforced.
    2) It is a MUST to align with the guidelines which especially means matching the reserved parameters and their semantic (minimal support means MUST support X-Total-Count in response header, offset + limit in query).
    3) As per 2), answer is actually 'no'. The all idea of guidelines is for all to match the same pattern, not to support heterogeneous 'flavors'.

    Summarizing: Pagination is currently stated as mamdatory (at least it should always be considered) and the guideline for its support is (only) as per pattern described in the guidelines (no other 'alternative').

    Kind regards,

    ------------------------------
    Christophe MICHEL
    Amdocs Management Limited
    ------------------------------



  • 8.  RE: Pagination: offset and limit

    TM Forum Member
    Posted 14 days ago
    Hi Christophe,

    Thanks for the reply.
    Actually, my doubt was originated as per the contents of the TMF630 specification, where we see two flavors
    (with examples) for the pagination:

    From Document:

    REST API Design Guidelines Part 1

    TMF630 (Team Approved Date:  08-May-2020)


    It's clear the offset + limit is the first choice but, at page 45, we have below request:
    (..)

    The following example shows how to use the Range header to iterate a collection of trouble
    tickets.
    The example assumes that 50 trouble tickets match a filtering criteria and that the maximum
    amount of trouble tickets being retrieved by calls is set by default to 10.

    REQUEST

    GET /api/troubleTicket?dateTime.gt=2013-04-20&status=acknowledged

    Accept-Range:items           

    Range:items=11-20 

    RESPONSE

    206 Partial Content

    Content-Type: application/json

    Content-Range: items 11-20/50

    [{

                         "id": "47",

                         "href": " /troubleTicketManagement/troubleTicket/47",

    :

    (..)

    So, in this example, TMF is not using the offset+limit to control the number of returned items in a collection
    but, the content-range pattern.

    So, from my understanding the options are:
    1) we assume that both are valid alternatives (as my original guess)
    2) an update on the guideline (TMF630) is required (as per above example)

    Regards,
    Marcos.

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



  • 9.  RE: Pagination: offset and limit

    TM Forum Member
    Posted 13 days ago
    Hi,

    The 2nd option (w/o offset+limit) is the old-fashioned / deprecated way of modelling such, which was kept in the guidelines for backwards compatibility reasons.
    So especially any new API should use the up-to-date, unique, guideline.

    Kind regards,

    ------------------------------
    Christophe MICHEL
    Amdocs Management Limited
    ------------------------------



  • 10.  RE: Pagination: offset and limit

    TM Forum Member
    Posted 13 days ago
    On Wednesday November 18, 2020 Christophe MICHEL wrote:
    > The 2nd option (w/o offset+limit) is the old-fashioned / deprecated way of modelling such, which was kept in the guidelines for backwards compatibility reasons.

    > So especially any new API should use the up-to-date, unique, guideline.

    It's frankly unsettling to hear the suggestion that the current IETF standard mechanism for pagination of collections (RFC7233) is "deprecated". I cannot express how strongly I disagree with this notion.

    ------------------------------
    Vance Shipley
    SigScale
    ------------------------------



  • 11.  RE: Pagination: offset and limit

    TM Forum Member
    Posted 13 days ago
    The alternative pagination method described in TMF630 requires the addition of a non-standard HTTP header X-Total-Count: whereas the IETF standards based pagination method uses the Content-Range: header standardized in RFC7233. In fact the use of "X-" headers was deprecated in RFC6648.

    Nothing in TMF630 should break, or unnecessarily limit, the IETF standards for HTTP.  A server receiving an HTTP GET with a Range: header may ignore it. So you can implement the more limited functionality of the alternative pagination method of TMF630 if you wish however RC7233 is the correct method.

    ------------------------------
    Vance Shipley
    SigScale
    ------------------------------



  • 12.  RE: Pagination: offset and limit

    TM Forum Member
    Posted 12 days ago
    Hi Vance,

    I think if you read the section in TMF guidelines dealing with pagination and mentioning actual support for Range in request / Content-Range in response your concern is clearly addressed, incl. how this is handled against the recommended guideline.
    This legacy solution has few drawbacks compared to recommended guideline, including what it leaves to (all) consumers to extract usually relevant information from there (like the total count needs to be extracted, what is next / previous page...) and also this solution was set before introducing hypermedia links which are relevant assets to cover here again direct access, compared to requirement to extract information and compute locally to the consumers.

    Kind regards,

    ------------------------------
    Christophe MICHEL
    Amdocs Management Limited
    ------------------------------



  • 13.  RE: Pagination: offset and limit

    TM Forum Member
    Posted 12 days ago
    @Christophe MICHEL ​ there is nothing "legacy" about RFC7233 and there is no intention to "deprecate" this standards based method of pagination in our APIs. Hypermedia links are an additional and completely non-conflicting issue.

    ------------------------------
    Vance Shipley
    SigScale
    ------------------------------



  • 14.  RE: Pagination: offset and limit

    TM Forum Member
    Posted 11 days ago
    @Vance Shipley don't get we wrong when using 'legacy' term here: this is about TMF legacy/previous guidelines, not long-living RFC. The pagination guideline in TMF has been re-adjusted, especially for the rationale I mentioned before. However RFC is still there and supported. There is no conflict as the TMF guidelines describe how to handle both, without 'competition' there. But the assumption is that the fresh guideline is recommended for any new API, embracing  benefits it brings.

    Kind regards,

    ------------------------------
    Christophe MICHEL
    Amdocs Management Limited
    ------------------------------