PUT/POST validation: warnings/errors
Jack Whelpton
Hi all,
Does anybody have any advice on how to include metadata in the response to a PUT or POST request that details problems that occurred during a save operation, but did not prevent creation of a resource? An example might clarify the problem. Suppose I have a widget resource:
{
"id": "AAA",
"name": "Widget A",
"model-number": "A123"
}
Name is a required field, and model number must contain only alphanumeric characters. Business rules prohibit the saving of an invalid object. Handling resource creation via a POST to /widgets is straightforward; the response is either 201 Created, with a body that includes the full representation and identical Location and Content-Location headers:
HTTP/1.1 201 Created
Location: /widget/AAA
Content-Location: /widget/AAA
{
"id": "AAA",
"name": "Widget A",
"model-number": "A123"
}
or 403 Forbidden with an HTTP problem details object, something like:
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"type": "http://problems.example.com/invalid-model-number",
"title": "Model number must contain only alphanumeric characters.",
"detail": "You attempted to create a widgets with a model number of '#A123', but this model number is invalid."
}
Now the business rules are changed slightly, so that if an attempt is made to save a widget with an invalid model number, the widget will be created without a model number and the client notified of the fact. We could extend the representation to include a "warnings" node, and populate it only on PUT/POST responses:
HTTP/1.1 201 Created
Location: /widget/AAA
Content-Location: /widget/AAA
{
"id": "AAA",
"name": "Widget A",
"warnings": [
{
"type": "http://problems.example.com/invalid-model-number",
"title": "Model number must contain only alphanumeric characters.",
"detail": "You attempted to create a widgets with a model number of '#A123', but such a model number is invalid."
}
]
}
However, I'm not sure adding this property is a particularly good idea; it could collide with a genuine property of widgets, and the Content-Location header is now not strictly accurate, as the included representation is not available at that URI (warnings are not persisted). We could separate the resource representation from any warnings:
HTTP/1.1 201 Created
Location: /widget/AAA
Content-Location: /widget/AAA
{
"result": {
"id": "AAA",
"name": "Widget A"
},
"warnings": [
{
"type": "http://problems.example.com/invalid-model-number",
"title": "Model number must contain only alphanumeric characters.",
"detail": "You attempted to create a widgets with a model number of '#A123', but such a model number is invalid."
}
]
}
Again, I suspect we would have to ditch the Content-Location header, and we'd probably want a custom link relation for performing these create/edit operations that detailed the result/warnings wrapper. This is probably the way I'm leaning at the moment.
A third option would be to continue to return a 403 and include enough information to allow the client to remove the offending elements and resubmit the request. This could become tricky in scenarios where the client is automated (a feed ingestion engine, for example) and the validation more complex.
Has anybody attempted anything similar and/or have suggestions that might help?
Thanks in advance,
Jack.
Jack Whelpton
Solution Architect
Direct Line: +44 1223484162
 |
| ************************************************************************************** |
| Confidentiality: This e-mail and any files transmitted with it are confidential and intended solely for the use of the individual or entity to whom they are addressed.
If you have received this e-mail in error please notify the sender immediately and delete this message from your computer without further action. Any views or opinions presented in this email are solely those of the author and do not necessarily represent
those of the company. Any dissemination, distribution or copying of this message or any files transmitted with it by an unauthorised recipient is strictly prohibited. Viruses: This message has been swept for viruses but we cannot guarantee that this e-mail or its attachments are virus free nor accept responsibility for any virus inadvertently transmitted herewith. |
| ************************************************************************************** |
Jørn Wildt
--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.
Chris Mullins
I've worked with API's in the past that offer a "Success with Info" style moniker. Without fail, these API's create customer angst, as developers seldom (Never!) properly code for these cases.
