Link Relations in JSON Representations

Question

I'm designing a RESTful API based on JSON representations. In order to comply with HATEOAS, I use links between resources extensively. Therefore, I followed this suggestion for serializing links in way very similar to ATOM links.

Now I have sometimes problems identifying the correct link relation type. When a resource contains a link to itself, the self relation is obvious. It gets more complex when the resources are collections and aggregations of sub-resources, or contain many links to related resources.

Take a blog post as an example, and think of a resource that returns a snapshot of the blog post – including the author, tags and comments of this blog post. Obviously, this resource contains many subresources and should of course also provides separate links to them:

Sample Resource:

{
   "blogpost":{
      "link":{
         "rel":"self",
         "href":"http://blog/post/4711"
      },
      "author":{
         "name":"Bob",
         "link":{
            "rel":"???",
            "href":"http://author/uri"
         }
      },
      "title":"foobar",
      "content":"A long article here…",
      "comments":[
         {
            "comment":"great article",
            "link":{
               "rel":"???",
               "href":"http://blog/post/4711/comment/1"
            },
            "author":{
               "name":"John Doe",
               "link":{
                  "rel":"???",
                  "href":"http://author/uri"
               }
            }
         }
      ],
      "tags":[
         {
            "value":"foo",
            "link":{
               "rel":"???",
               "href":"http://blog/post/4711/tag/foo"
            }
         }
      ]
   }
}

So what are appropriate relations for the given links? I know that there are relation types such as tag, but not all of my resources match the existing relation types. Or is it okay to use self when referring to the author/tag/comment, because it relates to the context of the enclosing JSON (sub-)object? What is the semantical entity self is referring to?

RFC 5988 states:

The context of the link is either a feed IRI or an entry ID, depending on where it appears

How can I interpret this in terms of JSON? Is each new object {…} a new context?

Thanks!

Bale

Answer 1

That is a great question. If you look at the example for Hal you will see that the rels are defined within the context of the sub-resource.
I do not know of any definitive guide on when the rel is related to the resource as a whole or a contained sub resource.
The only extra piece of information I can point you to is the anchor parameter in RFC5988 which allows you to redefine the context IRI using either a fragment or a completely new URI.

Ideally, your mediatype should state whether the context IRI is different for nested resources, or whether the context IRI needs to be explicitly changed. That would be another advantage of using a media type like application/vnd.hal+json instead of plain old application/json as the Hal spec states:

@rel - For identifying how the target URI relates to the 'Subject Resource'. The Subject Resource is the closest parent Resource element.

Nocuous

Answer 2

LSON-LD

You can maybe have a look at JSON-LD (JavaScript Object Notation for Linked Data. It looks like more complicated than HAL but you can do more with it.

JSON-LD is being standardized inside of the W3C, here is the proposal recommendation.

Also

• HAL vs JSON-LD (answered by Manu Sporny, creator of JSON-LD)
• JSON-LD articles and presentations
• Hydra (console)

Sorry I don't have time to provide with an example..

Langston

Answer 3

It's a bit late to answer that question but for future reference, this is how I solve this problem :

{
   "blogpost":{
      "title":"foobar",
      "content":"A long article here…",
      "link":{
         "rel":"self",
         "href":"http://blog/post/4711"
      },
      "link":{
         "rel": "author",
         "href": "http://author/uri",
         "alt":"Bob"
      },
      "link":{
        "rel": "comment",
        "alt": "great article",
        "href":"http://blog/post/4711/comment/1"
      },
      "link": {
        "rel":"tag",
        "href":"http://blog/post/4711/tag/foo",
        "alt":"foo"
      }
   }
}

when you think about it, comments, tags, etc are all distinct resources linked to your post ... why not then make them all what they are .. links ! You even save on the size of your response ;)

Thurstan

Whoah - you have duplicate keys there! Most JSON parsers will simply ignore duplicate keys, leaving you with only one of the links. Consider putting your links in an array instead. – Keithakeithley

This is a really bad example of API design. Other readers, please do not copy this! – Torrietorrin

Please, do NOT use this approach. – Fils