Master/Detail with 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

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 2

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.