Menu
All the articles and books I read on REST repeat the importance of adding "self" rel links to your hypermedia responses but they're all light on the reasons and use cases.
Why should you add a self link and how is it useful?
451
A self link is a link to the page on which the link appears. A self-link to a page receives different styling from traditional links – for example as bold text in Vector – when the article is viewed ("self-link feature").
The term “hypermedia” refers to any content that contains links to other forms of media such as images, movies, and text. REST architectural style lets us use the hypermedia links in the API response contents. It allows the client to dynamically navigate to the appropriate resources by traversing the hypermedia links.
A hypermedia API is an API that returns hypermedia, typically HTML over HTTP. This style of API is distinguished from data APIs that do not return a hypermedia. The most familiar form of this latter style of API today is the ubiquitous JSON API.
The main reason is that clients (and even some servers) do not store the location of a representation with the representation. For example, if you wget http://.../foo.json, the representation will be saved to disk, but the URI at which it was fetched will not be. If there is no "self" link embedded in the representation, this causes two problems:
Relative links in the document may no longer have a base against which to resolve, and will therefore be "broken"; and
The client will have no embedded concept of where to e.g. PUT the document back to a server if they modify it. A few clients maintain this information independently, but most do not.
It's important to understand that representations may have a life well outside the HTTP conversation, and may even be transferred via other protocols (e-mail, FTP, in a book, etc). An experienced media-type designer will therefore typically include a "self" link.
159
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
