3

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?

2
  • 1
    How about /profiles/:profile_id/childrenProfiles?
    – Mac70
    Commented Sep 22, 2016 at 12:47
  • 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) Commented Sep 22, 2016 at 13:12

1 Answer 1

5

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
2
  • 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? Commented Sep 22, 2016 at 14:06
  • 2
    @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. Commented Sep 22, 2016 at 14:30

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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