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.
------------------------------
Original Message:
Sent: Nov 26, 2021 12:42
From: Bhanu Sirigiri
Subject: TMF641 - Difference between REST API Guide & OpenAPI Spec
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
------------------------------