John John - 1 month ago 35
reST (reStructuredText) Question

Master/Detail with REST

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

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.