6 ms·

Nope, the current state of affairs is an indictment of the "standards". It should be easy and obvious to implement something according to the standards, but it'

Nope, the current state of affairs is an indictment of the "standards". It should be easy and obvious to implement something according to the standards, but it's not. I'm a relatively smart guy, and I've tried. You very quickly reach the point where you ask, "why the fuck am I doing this?" and just do what makes sense. Let's take RFC8288 as an example since you've brought it up. Where in that RFC does it discuss _why the fuck_ I would want to put an API link in the headers instead of the body? The fact is that this RFC isn't "the standard". The standard thing is to put API links in the body with other attributes, and it's the standard because that's what everyone does, and because that's what makes sense. This RFC is a hammer for HTTP pedants to hit people over the head with. The web is based on linking And where to we expect those links to appear? In the header?

niftich 7y ago
FWIW, RFC 8288 was preceded [1] by RFC 5988, and RFC 5988 [2] says in its section '1. Introduction': "A means of indicating the relationships between resources on the Web, as well as indicating the type of those relationships, has been available for some time in HTML [W3C.REC-html401-19991224], and more recently in Atom [RFC4287]. These mechanisms, although conceptually similar, are separately specified. However, links between resources need not be format specific; it can be useful to have typed links that are independent of their serialisation, especially when a resource has representations in multiple formats." "To this end, this document defines a framework for typed links that isn't specific to a particular serialisation or application. It does so by redefining the link relation registry established by Atom to have a broader domain, and adding to it the relations that are defined by HTML." [1] https://tools.ietf.org/html/rfc8288 https://tools.ietf.org/html/rfc8288 [2] https://tools.ietf.org/html/rfc5988 https://tools.ietf.org/html/rfc5988
- solipsism 7y ago
  it can be useful Such as in which situations? It's not obvious at all, so a reader (that is, an API designer) is on their own to try and divine whether there's any real reason to follow this "standard" instead of doing things in the more natural and standard way. This is my point. Not that it's hard to read these RFCs... but that they're often so vague, and is so often hard to know whether there's any benefit at all to following them in one's specific situation. That doesn't stop self-appointed standards cops from smacking people down.
- yawaramin 7y ago
  I might be missing the obvious, but I don't see in your quote the answer to the question: > Where in that RFC does it discuss _why the fuck_ I would want to put an API link in the headers instead of the body?
  - niftich 7y ago
    The answer is in the part that says "it can be useful to have typed links that are independent of their serialisation, especially when a resource has representations in multiple formats". 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.
    - yawaramin 7y ago
      Got it, thanks. How do you define 'the chosen representation can't communicate links in its body'?
      - niftich 7y ago
        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.
        yawaramin 7y ago
geezerjay 7y ago
> Nope, the current state of affairs is an indictment of the "standards". That's not true at all. Those "standards" are not taken into account at all. I mean, there are currently about half a dozen HATEOAS standards and specifications that repeatedly implement the same concept, and they have existed for quite a few years. Yet, how many of those standards and specifications were taken into account in this particular blog post? Zero. Instead of taking into account any prior work already done on the issue of web linking, the problem is for some reason presented as a novel idea that, for some reason, no one in the world would have ever thought about. How is that a reasonable starting point? > It should be easy and obvious to implement something according to the standards, but it's not. You got to be kidding. Let's consider RFC8288. RFC8288 in essence specifies a single HTTP header and a format to represent link relations. You want to link your resource to any other resources? Well, just add the link relations. You want to check what resources are related to the resource you've just requested? Well, just check the Links headers. Let's consider Hypertext Application Language (HAL). HAL in essence specifies a wrapper document type that extends the resource with a "_links" name:object pair. You want to link your resource to any other resources? Well, just add the link relations to the "_links" object. You want to check what resources are related to the resource you've just requested? Well, just check the object referred by the "_links" name. Let's consider the Ion Hypermedia Type. Ion in essence specifies a wrapper object type that includes all link relations as JSON name:value pairs and contains the resource as the value of the "value" name:value pair. You want to link your resource to any other resource? Well, just add the link relation as a name:value pair. You want to check what resources are related to the resource you've requested? Well, just check the name:value pairs of the response object. And the same applies to other HATEOAS standards and specifications such as JSON-LD, Hydra, Collection+JSON, Siren, etc etc etc... Where's the rocket science? > Where in that RFC does it discuss _why the fuck_ I would want to put an API link in the headers instead of the body? You can't be serious.
- joshuamorton 7y ago
  As someone who is wholly unfamiliar with this, why should relationships be treated any differently than any other attribute of some object returned by a web api? If data-attributes have to be parsed out of some json-body, but link-attributes have to be parsed out of the header, that's weird. It becomes even weirder if I decide to switch from using a key-in-the-body to a link-in-the-header. That doesn't sound easy or obvious. As is, as someone dealing with a REST API, I rarely, if ever, have to think of headers. When I do, they're related to things like CORS, and transport layer semantics, not application level semantics. But now you're saying that, actually, some of my application semantics should be in the header, but most should be in the body. How is that easy or obvious? Why is that better? I'm dead serious, I'm not kidding, I'm not the user you just responded to.

niftich 7y ago

FWIW, RFC 8288 was preceded [1] by RFC 5988, and RFC 5988 [2] says in its section '1. Introduction': "A means of indicating the relationships between resources on the Web, as well as indicating the type of those relationships, has been available for some time in HTML [W3C.REC-html401-19991224], and more recently in Atom [RFC4287]. These mechanisms, although conceptually similar, are separately specified. However, links between resources need not be format specific; it can be useful to have typed links that are independent of their serialisation, especially when a resource has representations in multiple formats." "To this end, this document defines a framework for typed links that isn't specific to a particular serialisation or application. It does so by redefining the link relation registry established by Atom to have a broader domain, and adding to it the relations that are defined by HTML." [1] https://tools.ietf.org/html/rfc8288 https://tools.ietf.org/html/rfc8288 [2] https://tools.ietf.org/html/rfc5988 https://tools.ietf.org/html/rfc5988

solipsism 7y ago
it can be useful Such as in which situations? It's not obvious at all, so a reader (that is, an API designer) is on their own to try and divine whether there's any real reason to follow this "standard" instead of doing things in the more natural and standard way. This is my point. Not that it's hard to read these RFCs... but that they're often so vague, and is so often hard to know whether there's any benefit at all to following them in one's specific situation. That doesn't stop self-appointed standards cops from smacking people down.
yawaramin 7y ago
I might be missing the obvious, but I don't see in your quote the answer to the question: > Where in that RFC does it discuss _why the fuck_ I would want to put an API link in the headers instead of the body?
- niftich 7y ago
  The answer is in the part that says "it can be useful to have typed links that are independent of their serialisation, especially when a resource has representations in multiple formats". 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.
  - yawaramin 7y ago
    Got it, thanks. How do you define 'the chosen representation can't communicate links in its body'?
    - niftich 7y ago
      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.
      - yawaramin 7y ago

geezerjay 7y ago

> Nope, the current state of affairs is an indictment of the "standards". That's not true at all. Those "standards" are not taken into account at all. I mean, there are currently about half a dozen HATEOAS standards and specifications that repeatedly implement the same concept, and they have existed for quite a few years. Yet, how many of those standards and specifications were taken into account in this particular blog post? Zero. Instead of taking into account any prior work already done on the issue of web linking, the problem is for some reason presented as a novel idea that, for some reason, no one in the world would have ever thought about. How is that a reasonable starting point? > It should be easy and obvious to implement something according to the standards, but it's not. You got to be kidding. Let's consider RFC8288. RFC8288 in essence specifies a single HTTP header and a format to represent link relations. You want to link your resource to any other resources? Well, just add the link relations. You want to check what resources are related to the resource you've just requested? Well, just check the Links headers. Let's consider Hypertext Application Language (HAL). HAL in essence specifies a wrapper document type that extends the resource with a "_links" name:object pair. You want to link your resource to any other resources? Well, just add the link relations to the "_links" object. You want to check what resources are related to the resource you've just requested? Well, just check the object referred by the "_links" name. Let's consider the Ion Hypermedia Type. Ion in essence specifies a wrapper object type that includes all link relations as JSON name:value pairs and contains the resource as the value of the "value" name:value pair. You want to link your resource to any other resource? Well, just add the link relation as a name:value pair. You want to check what resources are related to the resource you've requested? Well, just check the name:value pairs of the response object. And the same applies to other HATEOAS standards and specifications such as JSON-LD, Hydra, Collection+JSON, Siren, etc etc etc... Where's the rocket science? > Where in that RFC does it discuss _why the fuck_ I would want to put an API link in the headers instead of the body? You can't be serious.

joshuamorton 7y ago
As someone who is wholly unfamiliar with this, why should relationships be treated any differently than any other attribute of some object returned by a web api? If data-attributes have to be parsed out of some json-body, but link-attributes have to be parsed out of the header, that's weird. It becomes even weirder if I decide to switch from using a key-in-the-body to a link-in-the-header. That doesn't sound easy or obvious. As is, as someone dealing with a REST API, I rarely, if ever, have to think of headers. When I do, they're related to things like CORS, and transport layer semantics, not application level semantics. But now you're saying that, actually, some of my application semantics should be in the header, but most should be in the body. How is that easy or obvious? Why is that better? I'm dead serious, I'm not kidding, I'm not the user you just responded to.