Link Relations in JSON Representations

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!

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.

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..