5 ms·

Oh! If that's the sort of thing we're talking about, then I'm all for it. The proponents of Hypermedia APIs have been saying a lot of vague things about how it

by mjs 14y ago

Oh! If that's the sort of thing we're talking about, then I'm all for it. The proponents of Hypermedia APIs have been saying a lot of vague things about how it will enable automated clients, and I assumed that the clients they had in mind would be able to do something useful with arbitrary APIs. But it's clear from GitHub's API that it will do nothing of the sort: those link relations (and even concepts) are very much GitHub specific, and no machine will ever be able to figure out what to do with the them, what methods or media types the endpoints support, and so on. (I'm not sure that it adds very much over a text document that that gives the relations and how to generate endpoints, but at least it's cheap to produce, and not actively harmful.)

steveklabnik 14y ago
> The proponents of Hypermedia APIs have been saying a lot of vague things about how it will enable automated clients, and I assumed that the clients they had in mind would be able to do something useful with arbitrary APIs. Consider a web browser, or an RSS reader. These are generic hypermedia clients that consumer standardized media types. > But it's clear from GitHub's API that it will do nothing of the sort: those link relations (and even concepts) are very much GitHub specific, and no machine will ever be able to figure out what to do with the them, what methods or media types the endpoints support, and so on. Right. We're not talking about AI, we're talking about generic re-usable components. > (I'm not sure that it adds very much over a text document that that gives the relations and how to generate endpoints, but at least it's cheap to produce, and not actively harmful.) The point is that by forcing you to define the communications protocol up front, you de-couple clients and servers. This means that they can evolve separately. Think about the RSS example: new versions of RSS clients can be made, and the servers don't need to be updated, and servers can update themselves and their responses and you don't need a new version of the client to handle it. The other advantage is that if there are multiple services in the same product domain, and they use the same type, you get generic re-use of clients across services. Everyone spits out RSS, everyone consumes RSS.
- mjs 14y ago
  RSS is a great example, because about the most sophisticated link relation in RSS is a link. But there seems to be a big difference in kind between what's being suggested for hypermedia APIs and the example of RSS. With RSS, the client doesn't need to know very much--only one method is supported (GET), it corresponds to a click, and you'll almost always get one media type back (text/html). The IANA define some other generic link relations, but there seems to be a very big gap between generic link relations ("self", "back", and so forth), and application-specific link relations that are necessary for non-trivial apps. How is GutHub's API useful to hypermedia libraries? A "library" that could be shared between GitHub and a different endpoint would be maybe 10 lines of code? HAL has a bit more structure, but we're talking maybe 100 lines of code. (Versus URI templates, which must be hundreds of lines, and with much more complicated rules.)
  - steveklabnik 14y ago
    > But there seems to be a big difference in kind between what's being suggested for hypermedia APIs and the example of RSS. Well, RSS is just a simple example: its domain is small. Which is why it's nice to talk about. If you need bigger and more powerful things, than stuff gets complicated. > With RSS, the client doesn't need to know very much--only one method is supported (GET), I should have said ATOM and ATOMpub; it has a slightly more complex edit/delete workflow as well. > The IANA define some other generic link relations, but there seems to be a very big gap between generic link relations ("self", "back", and so forth), and application-specific link relations that are necessary for non-trivial apps. Right. The idea is that you use app specific ones at first, then, as you find they're useful and stable, you make them a generic one. > How is GutHub's API useful to hypermedia libraries? This is backwards. It's more like "how are hypermedia libraries useful for implementing the GitHub API."
    - mjs 14y ago
      > Right. The idea is that you use app specific ones at first, then, as you find they're useful and stable, you make them a generic one. Ok, but do you think there will will ever be a generic definition of "user" or "product" or "photo" that can access the full experience of e.g. Amazon, Google, Facebook, Flickr and GitHub? Regarding Atom, Google adopted a extended version of Atom in for some (but not all) of their products, but no-one else adopted it in almost a decade, and Google are now deprecating it. (I'm sort of blurring the difference between link relations and media types, but they seem entwined.) URIs and shared media types are great for interoperability, but my guess (we'll see if it comes true) is that pretty much anything beyond that isn't going to get traction. Hypertext was around before the web, but I think a big reason it took off is because had very loose interoperability demands. (e.g. links can break.)

by mjs 14y ago

steveklabnik 14y ago

> The proponents of Hypermedia APIs have been saying a lot of vague things about how it will enable automated clients, and I assumed that the clients they had in mind would be able to do something useful with arbitrary APIs. Consider a web browser, or an RSS reader. These are generic hypermedia clients that consumer standardized media types. > But it's clear from GitHub's API that it will do nothing of the sort: those link relations (and even concepts) are very much GitHub specific, and no machine will ever be able to figure out what to do with the them, what methods or media types the endpoints support, and so on. Right. We're not talking about AI, we're talking about generic re-usable components. > (I'm not sure that it adds very much over a text document that that gives the relations and how to generate endpoints, but at least it's cheap to produce, and not actively harmful.) The point is that by forcing you to define the communications protocol up front, you de-couple clients and servers. This means that they can evolve separately. Think about the RSS example: new versions of RSS clients can be made, and the servers don't need to be updated, and servers can update themselves and their responses and you don't need a new version of the client to handle it. The other advantage is that if there are multiple services in the same product domain, and they use the same type, you get generic re-use of clients across services. Everyone spits out RSS, everyone consumes RSS.

mjs 14y ago
RSS is a great example, because about the most sophisticated link relation in RSS is a link. But there seems to be a big difference in kind between what's being suggested for hypermedia APIs and the example of RSS. With RSS, the client doesn't need to know very much--only one method is supported (GET), it corresponds to a click, and you'll almost always get one media type back (text/html). The IANA define some other generic link relations, but there seems to be a very big gap between generic link relations ("self", "back", and so forth), and application-specific link relations that are necessary for non-trivial apps. How is GutHub's API useful to hypermedia libraries? A "library" that could be shared between GitHub and a different endpoint would be maybe 10 lines of code? HAL has a bit more structure, but we're talking maybe 100 lines of code. (Versus URI templates, which must be hundreds of lines, and with much more complicated rules.)
- steveklabnik 14y ago
  > But there seems to be a big difference in kind between what's being suggested for hypermedia APIs and the example of RSS. Well, RSS is just a simple example: its domain is small. Which is why it's nice to talk about. If you need bigger and more powerful things, than stuff gets complicated. > With RSS, the client doesn't need to know very much--only one method is supported (GET), I should have said ATOM and ATOMpub; it has a slightly more complex edit/delete workflow as well. > The IANA define some other generic link relations, but there seems to be a very big gap between generic link relations ("self", "back", and so forth), and application-specific link relations that are necessary for non-trivial apps. Right. The idea is that you use app specific ones at first, then, as you find they're useful and stable, you make them a generic one. > How is GutHub's API useful to hypermedia libraries? This is backwards. It's more like "how are hypermedia libraries useful for implementing the GitHub API."
  - mjs 14y ago
    > Right. The idea is that you use app specific ones at first, then, as you find they're useful and stable, you make them a generic one. Ok, but do you think there will will ever be a generic definition of "user" or "product" or "photo" that can access the full experience of e.g. Amazon, Google, Facebook, Flickr and GitHub? Regarding Atom, Google adopted a extended version of Atom in for some (but not all) of their products, but no-one else adopted it in almost a decade, and Google are now deprecating it. (I'm sort of blurring the difference between link relations and media types, but they seem entwined.) URIs and shared media types are great for interoperability, but my guess (we'll see if it comes true) is that pretty much anything beyond that isn't going to get traction. Hypertext was around before the web, but I think a big reason it took off is because had very loose interoperability demands. (e.g. links can break.)