RESTful nested resources

Question

I have a profile resource. Profiles can have a parent and an arbitrary number of child profiles.

What's the best way to model this in a RESTful scenario?

I thought of a number of different solutions, each with pros and cons:

/profiles/:profile_id/children

+ it's clear that we are querying the profile resource

- the last fragment of the URL doesn't state that we will return a list of profiles

/parents/:parent_id/profiles

+ it's not clear that we are querying the profile resource

- the last fragment of the URL clearly states that we will return a list of profiles

/profiles/:profile_id/profiles

+ it's clear that we are querying the profile resource

+ the last fragment of the URL clearly states that we will return a list of profiles

- the hierarchical relationship might not be clear

Any thought or suggestions on how to clearly model this scenario?

• Mac70: How about /profiles/:profile_id/childrenProfiles?
• Robin Vinzenz: Isn't it intended in RESTful to return always the whole resource and then operate on it's data? What I think is to retrieve the profile via id /profiles/<id> and then work on data you need (children and parents). (But this depends on your model behind a profile)

Answer 1

Ok, so REST doesn't say anything about what URIs should look like. There is no assumption or intent that URIs be human-readable. REST says to use HATEOAS, which in short means clients should be operating on named links, not URIs.

GET /profiles/12
{
 "id": 12,
 ...,
 "links": {
 "self": "/profiles/12",
 "parent": "/whatever-uri-you-want",
 "children": "/whatever-uri-you-want"
 }
}

In this case, clients who want the children ask the profile for the children URI and GET it. Clients don't care what the URI is, and you can even change it with some modicum of safety.

Assuming you're using REST to actually mean "Web API", and you require your clients to manually build URIs, then I'd go with @Mac70's suggestion and do something like

/profiles/{id}/child-profiles

• Andrea Casaccia: Thanks, I don't quite understand what you mean by "clients should be operating on named links, not URIs", can you explain a little more about that?
• Bart van Ingen Schenau: @AndreaCasaccia: The idea is that clients of your API don't need to know/guess that there is a .../children sub-resource under your /profiles/:id resource. Rather, the representation of the profile resource would contain a section listing the URIs for related resources, such as the list of children.