7

Suppose there is a primary resource "/accounts" which has Profile (name, national id, DOB), addresses and contacts(email, phones). I am considering them as sub-resources because they cannot exist without an account. To update them I am thinking two options

Option 1

  • PUT /accounts/{accountid}/address
  • PUT /accounts/{accountid}/contacts
  • PUT /accounts/{accountid}/profile

Option 2

  • PUT /accounts/{accountid}
    (Depending on the presence/absence of address/phone/profile decide which updates to perform)

I am tempted to use option 1 because from implementation perspective each of the updates have own logic & process flow. A separate URI may keep implementation cleaner & manageable

  1. Would it be incorrect to consider profile,address,contacts as subresources. if so, what would be an appropriate way of representing them
  2. If they can be considered sub-resources which among the above is an appropriate option or is there a completely different option to be considered
  • 3
    PUT is supposed to be an update-in-whole sort of action. At least in theory, you should be able to PUT to a resource and then immediately GET that same resource; the GET should return exactly the same thing that you previously PUT. In particular this suggests that a PUT of a partial resource (eg updating only the address of an account) is not idiomatic. The spec is fairly clear on the different purposes of PUT and POST. – Benjamin Hodgson Jan 26 '16 at 0:19
  • @BenjaminHodgson - Can't we use 'PUT' if we are referring to address subresource while updating with a qualified URI /accounts/{accountid}/address. In that case the action is idempotent because whatever address was "PUT" can be immediately "GET" irrespective of how many time same address was "PUT". – sbhas Jan 28 '16 at 0:42
4

Would it be incorrect to consider profile,address,contacts as subresources.

No, anything you like can be a subresource. REST doesn't care (a subresource is a resource), and using paths is appropriate URI design for hierarchical elements.

is there a completely different option to be considered?

You might want edits directed to finer resources though. The PUT method is great for idempotent edits. It's a little twitchy for partial edits - officially, the http specification "does not define how the PUT method affects the state of the origin server"; but it's widely understood that put is supposed to include a complete representation of the resource, with create or replace semantics.

For example: if you are always going to edit all three fields of the profile together, then using a single resource to modify the lot is appropriate. On the other hand, if you want to support replacing the date of birth without bothering the other fields, then you'll surprised fewer people if you write the change to a dedicated subresource (ie: /accounts/{accountId}/profile/dob).

This is a general concern: do you update a resource by modifying it directly, or do you induce changes in it by modifying a subresource. For instance, you seem to have multiple contacts in your definition -- it might be appropriate to accepts edits to contacts directly, or it may be that the representation of contacts is instead a reflection of the edits performed on contacts/email or contacts/phone.

  • Thanks. Agreed that in case of address & phone PUT might be suitable by referring to subresource directly because the data will be updated in entirety but in case of profile , PUT will break the rule because end user can just update DOB without updating SSN. Should we opt for POST instead? If we start expanding URI by adding 3-4 levels of subresources, where do we draw the line? As you can see, I too have same concern but trying to find a pragmatic answer. – sbhas Jan 28 '16 at 0:50
1

HTTP and REST don't care if a resource is a "sub-resource", they have no structural knowledge of a "can't exist without" constraint.

From a consistency perspective, if PUT is allowed for a "sub-resource" I would at least expect to be able to GET it separately from its parent resource as well. Then a strict level 3 REST approach (HATEOAS) would also probably recommend to put a hypermedia link to the Address resource in the response for GET Account instead of directly including Address data there.

  • nice link btw, thanks! – the0ther May 15 at 20:55

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.