Should JSON representation of REST resources use URIs for related resources?

Question

Is it a best practice of using URIs in JSON (or XML) representation of REST resources, for example

For example for a resource which has a list of attachments, where every attachment has an id which can be used to retrieve it using an URL like http://myserver.com/resources/attachments/:

{
    fileName: "screenshot.png"
    contentType: "application/octet-stream"
    id: 52004
}

Should I also add an uri element like

{
    fileName: "screenshot.png"
    contentType: "application/octet-stream"
    id: 52004
    uri: /resources/attachments/52004
}

Answer 1

Yes, I think you should include a link to each item in the collection. An API is not RESTful (and more importantly, not as useful) without the links. If you think a human client would rather have a link than instructions on how to request an item by ID, the same applies to a non-human client. You should also give the client some idea of how the item relates to the current resource by providing a link relationship:

link : { uri: "/resources/attachments/52004", rel: "/rels/file-attachment" }

John