REST API - Handling subresources

Question

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

Answer 1

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.

Answer 2

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.