Search code examples
restapi-design

RESTful API design: Is providing a specific sub-URI for a specific resource's properties something one should encourage/avoid?

Designing an API as RESTful as possible, I wonder if it is ok to divide a resource with specific sub-URIs.

Let's have the following URIs:

  • GET /users: list users

  • GET /users/42: get detailed information about user with id=42, e.g.:

    {
    id: 42,
    first_name: "Done",
    last_name: "Joe",
    is_active: false
}

I am about to consider the "is active" status as its own resource:

  • GET /users/42/is_active: get activity status about user with id=42

    {
    is_active: false
}

  • PUT /users/42/is_active: set activity status about user with id=42 using as body:

    {
    is_active: false
}

Any pro's or con's for doing so?

Solution

  • What you're talking about is called a "micro-resource". It's useful for doing partial updates in an idempotent manner. It's not popular in more well-known APIs, but it's certainly a valid design approach.