Open APIs

Hi Team , 

• What should be the REST API behavior when user tries to pass additional fields which are not defined in model (schema). e.g. if  employee schema has firstName, lastName , gender. User input request json has firstName, lastName, gender and department. system should process request by consuming required fields or error out request ?
• In above example assuming gender is non modifiable (immutable) field. User is trying to update gender field in PUT operation. API should ignore the modified value in request or report an error ? 
  Thanks 

Prashanth 

------------------------------
prashanth kumaraswamy
TO BE VERIFIED
------------------------------

Hi Prashanth

I'll assume you are referring specifically to TMF Open APIs, not to REST APIs in general. I hope there are some experts out there who can relate to the more general query, you could try https://www.stackoverflow.com or similar forums for general REST semantic enquires.

A few points:

• We don't use PUT any more in Open APIs - you won't see it in swagger/OAS files (although you may find it in some of the older API assets).
• In both v4 and v5 we generate dedicated resource definitions for POST and for PATCH, according to the business rules that the API designer specifies. So in your example, if gender was immutable, the POST definition for Individual would have gender property but the PATCH definition would not. In v4 these are named <Entity>_Create and <Entity>_Update, while in v5 these are named <Entity>_FVO and <Entity>_MVO

In my opinion, API implementations should be forgiving with respect to additional fields as input to operations - if the implementation doesn't recognize a field then it should ignore it. You are dependent to some extent on the foundation that you use for deserialization from payload to programming language representation.

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

Thank you very much for your inputs. kindly help me with some reference where i can gather more details on <Entity>_Create and <Entity>_Update

As an extension to earlier question TMF 630 defines POST operation should be used for create and PUT / PATCH can be used for modify. will Open API standards allow us to use POST operation to modify an existing  customer or account entity 

Thanks 
Prashanth  

------------------------------
prashanth kumaraswamy
TO BE VERIFIED
------------------------------

Original Message:
Sent: Dec 28, 2023 01:51
From: Jonathan Goldberg
Subject: Open API standard for immutable attributes.

Hi Prashanth

I'll assume you are referring specifically to TMF Open APIs, not to REST APIs in general. I hope there are some experts out there who can relate to the more general query, you could try https://www.stackoverflow.com or similar forums for general REST semantic enquires.

A few points:

• We don't use PUT any more in Open APIs - you won't see it in swagger/OAS files (although you may find it in some of the older API assets).
• In both v4 and v5 we generate dedicated resource definitions for POST and for PATCH, according to the business rules that the API designer specifies. So in your example, if gender was immutable, the POST definition for Individual would have gender property but the PATCH definition would not. In v4 these are named <Entity>_Create and <Entity>_Update, while in v5 these are named <Entity>_FVO and <Entity>_MVO

In my opinion, API implementations should be forgiving with respect to additional fields as input to operations - if the implementation doesn't recognize a field then it should ignore it. You are dependent to some extent on the foundation that you use for deserialization from payload to programming language representation.

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

See my answer on the other thread that you opened:

https://engage.tmforum.org/discussion/post-operation-to-update-existing-customer

------------------------------
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: Dec 28, 2023 03:39
From: prashanth kumaraswamy
Subject: Open API standard for immutable attributes.

Hi Jonathan, 

Thank you very much for your inputs. kindly help me with some reference where i can gather more details on <Entity>_Create and <Entity>_Update

As an extension to earlier question TMF 630 defines POST operation should be used for create and PUT / PATCH can be used for modify. will Open API standards allow us to use POST operation to modify an existing  customer or account entity 

Thanks 
Prashanth  

------------------------------
prashanth kumaraswamy
TO BE VERIFIED
------------------------------


Original Message:
Sent: Dec 28, 2023 01:51
From: Jonathan Goldberg
Subject: Open API standard for immutable attributes.

Hi Prashanth

I'll assume you are referring specifically to TMF Open APIs, not to REST APIs in general. I hope there are some experts out there who can relate to the more general query, you could try https://www.stackoverflow.com or similar forums for general REST semantic enquires.

A few points:

• We don't use PUT any more in Open APIs - you won't see it in swagger/OAS files (although you may find it in some of the older API assets).
• In both v4 and v5 we generate dedicated resource definitions for POST and for PATCH, according to the business rules that the API designer specifies. So in your example, if gender was immutable, the POST definition for Individual would have gender property but the PATCH definition would not. In v4 these are named <Entity>_Create and <Entity>_Update, while in v5 these are named <Entity>_FVO and <Entity>_MVO

In my opinion, API implementations should be forgiving with respect to additional fields as input to operations - if the implementation doesn't recognize a field then it should ignore it. You are dependent to some extent on the foundation that you use for deserialization from payload to programming language representation.

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

The behaviour is not defined by the REST specification but rather by the JSON / JSONSchema specification.

TMForum OpenAPI v4 is based on swagger where some of the rules were still fuzzy.

TMForum OpenAPI v5 is based on the OAS3 which uses a dialect of JSON-Schema.

JSON-Schema by default uses an open content model. This means that additional fields can be added without breaking the validation rules. Applications should gracefully ignore the fields they don't understand. If a closed content model is required the JSON-Schema should have the additional property:"additionalProperties": false . As far as I know this is never used in the TMF OAS3 definitions.

The concept of immutable fields is a bit more difficult. JSON-Schema support the "readOnly" property to indicate that a field can't be written by an API (e.g. PATCH) but is still retrievable. To my knowledge this is also never used by the current TMForum OpenAPI specifications.

In my view the application that is going to ignore the value in case should report an error rather than ignoring a known field. This will avoid unexpected behaviour.

Not everything is captured in rules, so probably you will have to implement what you believe is common sense.

Regards

------------------------------
Koen Peeters
OryxGateway FZ LLC
------------------------------