Re:Use links not keys to represent relationships in APIs
by yawaramin on Sunday May 12, 2019 @11:07AM
(#19892340)
Got it, thanks. How do you define 'the chosen representation can't communicate links in its body'?
Re:Use links not keys to represent relationships in APIs
by niftich on Sunday May 12, 2019 @10:22PM
(#19895990)
You as the client try to GET /my-receipts/20190512-1 from Fancy Receipt Scanning Service, and content-negotiate with an Accept header to "text/plain" or "image/gif" (e.g. to get a plain copy or a scan). There's no agreed-upon way of communicating links in plain text or GIF, so Fancy Receipt Scanning Service can't serve you a GIF scan of your receipt that links to a product page for every item you bought.
If you accepted "text/html", it could have served HTML that embedded these links within the response body, but you didn't accept "text/html".
It can choose to send links as headers, if it still wishes to communicate links.
In HTTP, URLs locate a 'resource'. Then you and the server do content negotiation, implicit and/or explicit, to select a 'resource representation'. Think of these as different formats for the same conceptual thing identified by the URL. Some formats like HTML can support hypermedia that can have embedded links. Some, like 'text/plain' or 'image/gif', can't.
Link headers allow links from the current resource to other resources to be communicated even if the chosen representation can't communicate links in its body.