REST API Should I return all nested resources when getting resource-CodePudding

Suppose that I have two endpoints: /users and /users/:id/discussions. And here are examples of possible responses to GET /users/1

{
  "user": {
    "name": "User1",
    "id": "1",
    "discussions": [<discussionsList>]
  }
}

{ 
  "user": {
    "name": "User1", 
    "id": "1" 
  }
}

Is it ok by REST principles if GET /users/1 returns response 2. and have a separate request GET /users/1/discussions to fetch discussions sub collection for user or is it not?

CodePudding user response：

Is it ok by REST principles if GET /users/1 returns response 2. and have a separate request GET /users/1/discussions to fetch discussions sub collection for user or is it not?

Almost, but not quite. REST principles would ask: how does the client know that /users/1/discussions is the right URI to use?

If your representation were instead something like:

{ 
  "user": {
    "name": "User1", 
    "id": "1" 
  },
  "discussions": "/users/1/discussions"
}

then the answer would be easy -- discussions gives you the URI that you need.

Somewhat more common is to have a collection of URI

{ 
  "user": {
    "name": "User1", 
    "id": "1" 
  },
  "links: {
    "self": "/users/1",
    "discussions": "/users/1/discussions"
  }
}

application/hal json is one example of a JSON media type that handles links this way.

You can also include links in headers

Link: </users/1/discussions>; rel="discussions"; anchor="/users/1"

If you are going to be compliant with RFC 8288, then you would need to choose between using a registered link relation, registering a new link relation, or using an extension relation.

The last of these options is most common. An RFC 8288 compliant extension relation is supposed to be a "URI that uniquely identifies the relation type". So you might instead see something like:

Link: </users/1/discussions>; rel="https://example.org/discussions"; anchor="/users/1"

Reading the RFC 8288, I'm unable to figure out what should rel point to? Could you please explain what's the point of that field? Does it needs to be some URI or not?

The point of the field is that the value tells you what the relationship is between the anchor and the target.

Link: </page/1>; rel="first"; anchor="/users/4"
Link: </page/5>; rel="next"; anchor="/users/4"

These two relations tell you that /page/5 comes after /page/4, and that /page/1 is the first page in the sequence.

We can use "first" and "next" here because both of those link relation types are registered with IANA. (To my great surprise, the references for both of these point to RFC 8288; it is probably better to understand them as described in RFC 5023).

But "discussions", the example we are using here, isn't a registered link relation type. Which means that we need to use a URI. That URI doesn't need to be an HTTP URI, and it doesn't have to be something that can be downloaded. But a convenient trick is to choose the URI of the document that explains the semantics of the link relation (ie: the text that explains what does

Link: </A; rel="https://example.org/discussions"; anchor="/B"

mean. So it's probably going to be a link into the documentation of your API, possibly the document that describes the schema of your JSON representations of your information.