Open APIs

Upon receiving a create order request, a server should return some sort of a sync-response.
Here is an example from 18.5.1:

{
    "id": "11", 
    "href": "https://host:port/serviceOrder/11"
}

Unfortunately, the specification does not define how a server should process exceptional cases. Assume a request from a client is malformed (is not a valid JSON). How the server should respond to this? Should it be a non-201 HTTP code? Or some error-indication in a payload?

Cheer,
Alexander

------------------------------
Alexander Morozov
Vlocity
------------------------------

Hi Alexander
The swagger file for each Open API lists a standard set of HTTP return codes, this set is generated by the tooling that we use and is identical for the same operation for all (recently-published) APIs.
Thus POST failures include 400, 401, 403, 405, 409, together with an Error structure that can be used to communicate more details of the error.

You should choose the relevant HTTP code and then fill the error structure (copied below) with more specific information.

Hope it helps

"code": {
"type": "string",
"description": "Application relevant detail, defined in the API or a common list."
},
"reason": {
"type": "string",
"description": "Explanation of the reason for the error which can be shown to a client user."
},
"message": {
"type": "string",
"description": "More details and corrective actions related to the error which can be shown to a client user."
},
"status": {
"type": "string",
"description": "HTTP Error code extension"
},
"referenceError": {
"type": "string",
"format": "uri",
"description": "URI of documentation describing the error."
},

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