Let's assume there are two resources Binder
and Doc
with association relationship meaning that the Doc
and Binder
stand on their own. Doc
might or might not belong to Binder
and Binder
might be empty.
If I want to design a REST API that allows a user to send a collection of Doc
s, IN A SINGLE REQUEST, like the following:
{
"docs": [
{"doc_number": 1, "binder": 1},
{"doc_number": 5, "binder": 8},
{"doc_number": 6, "binder": 3}
]
}
And for each doc in the docs
,
doc
exists then assign it to Binder
doc
doesn't exist, create it and then assign itI'm really confused as to how this should be implemented:
/binders/docs
?PUT ing
PUT /binders/{id}/docs
Create or update, and relate a single document to a binder
e.g.:
PUT /binders/1/docs HTTP/1.1
{
"docNumber" : 1
}
PATCH ing
PATCH /docs
Create docs if they do not exist and relate them to binders
e.g.:
PATCH /docs HTTP/1.1
[
{ "op" : "add", "path" : "/binder/1/docs", "value" : { "doc_number" : 1 } },
{ "op" : "add", "path" : "/binder/8/docs", "value" : { "doc_number" : 8 } },
{ "op" : "add", "path" : "/binder/3/docs", "value" : { "doc_number" : 6 } }
]
I'll include additional insights later, but in the meantime if you want to, have a look at RFC 5789, RFC 6902 and William Durand's Please. Don't Patch Like an Idiot blog entry.
In a project I worked at we solved this problem by implement something we called 'Batch' requests. We defined a path /batch
where we accepted json in the following format:
[
{
path: '/docs',
method: 'post',
body: {
doc_number: 1,
binder: 1
}
},
{
path: '/docs',
method: 'post',
body: {
doc_number: 5,
binder: 8
}
},
{
path: '/docs',
method: 'post',
body: {
doc_number: 6,
binder: 3
}
},
]
The response have the status code 207 (Multi-Status) and looks like this:
[
{
path: '/docs',
method: 'post',
body: {
doc_number: 1,
binder: 1
}
status: 200
},
{
path: '/docs',
method: 'post',
body: {
error: {
msg: 'A document with doc_number 5 already exists'
...
}
},
status: 409
},
{
path: '/docs',
method: 'post',
body: {
doc_number: 6,
binder: 3
},
status: 200
},
]
You could also add support for headers in this structure. We implemented something that proved useful which was variables to use between requests in a batch, meaning we can use the response from one request as input to another.
Facebook and Google have similar implementations:
https://developers.google.com/gmail/api/guides/batch
https://developers.facebook.com/docs/graph-api/making-multiple-requests
When you want to create or update a resource with the same call I would use either POST or PUT depending on the case. If the document already exist, do you want the entire document to be:
In case you want the behavior from alternative 1 you should use a POST and in case you want the behavior from alternative 2 you should use PUT.
http://restcookbook.com/HTTP%20Methods/put-vs-post/
As people already suggested you could also go for PATCH, but I prefer to keep API's simple and not use extra verbs if they are not needed.
You probably will need to use POST or PATCH, because it is unlikely that a single request that updates and creates multiple resources will be idempotent.
Doing PATCH /docs
is definitely a valid option. You might find using the standard patch formats tricky for your particular scenario. Not sure about this.
You could use 200. You could also use 207 - Multi Status
This can be done in a RESTful way. The key, in my opinion, is to have some resource that is designed to accept a set of documents to update/create.
If you use the PATCH method I would think your operation should be atomic. i.e. I wouldn't use the 207 status code and then report successes and failures in the response body. If you use the POST operation then the 207 approach is viable. You will have to design your own response body for communicating which operations succeeded and which failed. I'm not aware of a standardized one.
Source: Stackoverflow.com