Open APIs

 View Only
  • 1.  TMF641 - Difference between REST API Guide & OpenAPI Spec

    Posted Nov 26, 2021 12:42
    Hi,

    There are few differences I observed in the REST API PDF Guide & the OpenAPI(Swagger) spec. CTK seems to be working as per OpenAPI Spec.
    Which one should we take as the truth ? 

    e.g.: Post /serviceOrder returning simply order id and href in PDF. Whereas the OpenAPISpec is returning complete order payload in response along with order id, state, etc.

    I see there are 2 things in OpenAPI spec, which is raising questions on response payload. What is the need to return all "order and service order item" in POST /serviceOrder & also in "GET /serviceOrder" i.e. get all orders ? This is overfeeding the data in response and also beating the purpose of href.

    Thanks in advance.

    ------------------------------
    Bhanu Sirigiri
    BT Group plc
    ------------------------------


  • 2.  RE: TMF641 - Difference between REST API Guide & OpenAPI Spec

    TM Forum Member
    Posted Nov 27, 2021 13:36
    Hi Bhanu

    The examples in user guide are ILLUSTRATIVE, not NORMATIVE. The swagger, as the technical definition of the API, is the correct source of truth.

    In this specific example (POST service order), the user guide says:
    • We use the 'fields' parameter to restrict the numbers of attributes returned in the response.
    But this is actually problematic, since fields is a query parameter, relevant for GET and not POST.

    I think we need to look at this again in the Open API team - since seemingly there is no need to return the full entity on POST or PATCH, only calculated fields (e.g. id, href, perhaps status, and others, depending on the specific resource).

    Regarding GET, I don't see a problem. In the example for GET by ID, the fields parameter was not supplied so indeed the entire resource is returned, as expected.

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



  • 3.  RE: TMF641 - Difference between REST API Guide & OpenAPI Spec

    Posted Nov 28, 2021 22:56
    Thanks Jonathan for the response.

    I'll refer OpenAPI Spec now onwards for final answer. 

    I agree on "GET for a Single Service Order" should return Service Order Item. I feel "GET for Listing Service Orders"  should not need to return all the Service Order Items, rather the calculated fields against Service Orders. 
    Can you share your thoughts on those ?

    ------------------------------
    Bhanu Sirigiri
    BT Group plc
    ------------------------------



  • 4.  RE: TMF641 - Difference between REST API Guide & OpenAPI Spec

    TM Forum Member
    Posted Nov 29, 2021 03:56
    Hi Bhanu
    By default, GET returns the entire entity and all its sub-entities (but <entity>Ref are not expanded). Doesn't matter whether GET by ID (retrieve) or GET without ID (search).
    To control the amount of information, you have the fields directive, and also JSON Path masking for APIs that choose to implement it (as described in design guidelines TMF630 chapter 6).

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



  • 5.  RE: TMF641 - Difference between REST API Guide & OpenAPI Spec

    Posted Nov 29, 2021 07:54
    Thanks Jonathan for the response. It makes sense.

    ------------------------------
    Bhanu Sirigiri
    BT Group plc
    ------------------------------