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 

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.

Original Message:
Sent: Dec 28, 2023 01:32
From: prashanth kumaraswamy
Subject: Open API standard for immutable attributes.

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

Original Message:
Sent: Dec 28, 2023 01:32
From: prashanth kumaraswamy
Subject: Open API standard for immutable attributes.

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