Open APIs

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

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

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

Original Message:
Sent: Nov 27, 2021 13:36
From: Jonathan Goldberg
Subject: TMF641 - Difference between REST API Guide & OpenAPI Spec

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

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

Original Message:
Sent: Nov 28, 2021 22:56
From: Bhanu Sirigiri
Subject: TMF641 - Difference between REST API Guide & OpenAPI Spec

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


Original Message:
Sent: Nov 27, 2021 13:36
From: Jonathan Goldberg
Subject: TMF641 - Difference between REST API Guide & OpenAPI Spec

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.

Thanks Jonathan for the response. It makes sense.

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

Original Message:
Sent: Nov 29, 2021 03:55
From: Jonathan Goldberg
Subject: TMF641 - Difference between REST API Guide & OpenAPI Spec

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


Original Message:
Sent: Nov 28, 2021 22:56
From: Bhanu Sirigiri
Subject: TMF641 - Difference between REST API Guide & OpenAPI Spec

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


Original Message:
Sent: Nov 27, 2021 13:36
From: Jonathan Goldberg
Subject: TMF641 - Difference between REST API Guide & OpenAPI Spec

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.