Master/Detail with REST - rest

Question

I'm sure this topic must have been covered off before so I'm happy to be pointed to any articles etc that I may have missed while searching.
I need to implement a very simple REST API to add and retrieve records in a master/detail relationship. My two options are below:
OPTION 1
POST /master
POST /master/[id]/details
GET /master/[id]
GET /master/[id]/details
PROS
Feels more 'RESTful'
Can retrieve fine-grained data for performance
CONS
A master doesn't make sense without at least one detail. How to handle atomicity? Compensating DELETE on the master if the detail fails when adding?
Multiple calls required to retrieve the master/detail set
OPTION 2
POST /master_and_details
GET /master_and_details/[master id]
PROS
Easy to manage atomicity
CONS
More complex structure to manage
GETs must return entire structure (not always efficient)
Doesn't feel very 'RESTful'
Thanks,
John

Answer 1

REST more or less dictates option 1, option 2 is just a plain old http api.
Your statement that a master makes no sense without at least one detail is probably wrong. You have no idea how your api will be used in the future by clever developers. You can guess, but you don't really know.
If you really need the compound solution yourself you could always add an interface at a higher level that calls onto the two separate interfaces and returns a compound object.
Option 1 allows the possibility of a microservice implementation -- or at least, a separation of concerns into two separable objects. Option 2 alone would not.

Answer 2

At least for sake of argument, and risking my meager reputation, I'll venture a third approach.
You'd have two resources: master and detail. (not "details", unless you want to go totally plural, in which case you'd have "masters" and "details"). The representation of master would include the collection of details, or (better) link relations to the details. Consider https://www.rfc-editor.org/rfc/rfc6573 for that link relation.
Therefore GET of master includes (directly or indirectly via relation) the collection of detail. POST/PUT of master can also POST/PUT detail members by their presence in the form data.
Any detail can also be GET/PUT/POSTED independently of the master. Here, the design depends somewhat on whether a detail has its own primary key, vs. using a composite key with its master. If it has its own primary key then you could have:
GET /detail/{detailKey} - gets specific detail
POST /detail - creates new detail
GET /master/{masterkey}/detail -- gets all details for master
GET /master{masterkey}/detail/{detailkey} -- get specific detail
obviously, on the POST, the data must include the key of the master.
You see that there is more than one URI for getting a detail. I don't think that that's wrong, but it does introduce some ambiguity: if detailKey is not actually a child of masterKey, do you 404? I'd say yes.
if the detail uses a composite key, then it can't be GETed independently of the master, so the first form shown above could not be supported. Also, {detailKey}, as used in the last example above, would be the identifier of the detail item within the master (typically a sequence number).

Answer 3

I would definitely go with Option 1, as Option 2 has nothing to do with REST. But that does not mean, that you need to use multiple querys to get Master + Detail.
As the Detail belongs to the Master (and so it is part of it), in my opinion it is absolutely ok to return Master and the Detail, when querying the Master.
You might also consider using a parameters to control whether to send the Detail or not.
So instead of executing GET /master/1 you could use GET /master/1?detail=true.
For POST and PUT more or less the same would work. Just instead of having the query parameter, you have a "section" in your body regarding the Detail.
An Example using JSON:
{
"data": {
"name": "master",
"detail": [
{
"name": "detail1"
},
{
"name": "detail2"
}
]
}
}
A POST with this data could create a Master with the name "master" and 2 Details for this Master.
As #ElroyFlynn stated before, the Details could also be accessible without the Master, if this makes sence.
Think about a forum with Threads and Posts. Usualy a Thread is the Master and every Post is a Detail. But if you want to search all Posts of the last hour, you definitely want to query the posts directly (the query could be something like GET /post?max_age=1h).
Also I don't agree, that a Master without Detail does not make sence. There might be cases, where it doesn't, but in the case of the forum, a Thread on it's own makes sence.
For the atomicity:
It depends on the case: If you delete a User you usually keep his Posts (even here on StackOverflow). If you instead delete a Thread, I guess, you can delete the Posts to.