Rel on REST API collection links

Question

I'm working on a REST API, and one of my resources is a collection of other resources, so I should return something like that:

{
    "Links":[
        {
            "Href":"http://my.rest.api/document/1",
            "Rel":"something"
        },
        {
            "Href":"http://my.rest.api/document/2",
            "Rel":"something"
        }
    ]
}

My question is about the "rel" property. I don't really understand its use. Is it something to specify which HTTP method to use? Can somebody explain me?

Thanks a lot

Answer 1

HTML 4 defines a set of link types . Key for their understanding is this sentence:

User agents, search engines, etc. may interpret these link types in a variety of ways. For example, user agents may provide access to linked documents through a navigation bar.

The same is true for REST. Server and client must agree about the meaning for the possible values of rel . These come to mind:

• parent : the parent collection a Resource is a child of
• next : the next Resource in a collection (if the collection is ordered)
• prev : the previous Resource in a collection (if the collection is ordered)
• children : a collection of child resources

There can be many more. The concrete rel values heavily depend on your Resources.

Edit: The rel attributes say nothing about HTTP verbs. They only give a hint about the nature of the relation of the current Resource to a different Resource.

Answer 2

They're a descriptor for how the target resource relates to the current resource. You can make your own up, or use established ones.

http://www.iana.org/assignments/link-relations/link-relations.xhtml

If they're stable in your API, then you can build client apps that look for the rel they're interested in from your links, then deference the href to advance to it.

For example, you may return:

"links":
[
    {
        "href": "/items",
        "rel": "collection"
    },
    {
        "href": "/items/123",
        "rel": "delete"
    }
]