I didn't want to create yet another issue for this so I'll put it here:

@wycats discarded HAL because:

HAL embeds child documents recursively, while JSON API flattens the entire graph of objects at the top level. This means that if the same "people" are referenced from different kinds of objects (say, the author of both posts and comments), this format ensures that there is only a single representation of each person document in the payload.

I like the idea of flattening the object graph. It make sense for top level entities like author but I don't think it will always make sense in every case: what about relationships of composition, where one entity owns the lifecycle of the entities on the other side of such relationship?. Examples: "Post and Comments" and the textbook example "Order and OrderItems". Both Comments and OrderItems don't make sense without their respective parent entities and I don't think it would make sense to list these entities as top level entities in the document. Also, I would consider the duplication of these entities a smell because they should be encapsulated by their parent entity.

Now, iff this point is considered, this would be my suggestion to achieve it (which may be a big change):

Instead of having a links attribute, list the relationships like any other member of an object. That member can contain a link (which can be seen as a proxy to the nested document) or the nested document itself:

Instead of

{ "id":"123",
  "title": "foo",
  "body": "bar",
  "links": {
    "comments": "http://api.example.com/post/123/comments",
    "author": "http://api.example.com/people/22"
  }
}

I'd do:

{ "id":"123",
  "title": "foo",
  "body": "bar",
  "comments": {
    "href": "http://api.example.com/post/123/comments"
    // using an object is more extensible (profiles?) because we can fit more info here if needed
  },
  "author": {
    "href": "http://api.example.com/people/22"
  }
}

Allow relationships to be:
- present (the nested document) (next example with comments)
- a link to a remote document (above)
- a link to another resource in the same document (next example with author)

{ 
"posts":[{
  "id":"123",
  "title": "foo",
  "body": "bar",
  "comments": [{ // comments are included
    "id":"333",
    "message":"laame"
   },{
    "id":"334",
    "message":"I disagree"
   }],
  "author": {
    "href": "http://api.example.com/people/888" // or any other way of pointing to the current document.
  }
}],
"people":[{
  "id":"888",
  "name":"John"
}]
}

The example is incomplete to avoid making this comment even longer.

Thoughts?

FAQ page #1

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions