4 ms·

I blogged about this same idea in response to a different article 3 months ago. Seems like the hypermedia discussion keeps coming up. Here's my response artic

by RTigger 14y ago

I blogged about this same idea in response to a different article 3 months ago. Seems like the hypermedia discussion keeps coming up. Here's my response article: http://rtigger.com/blog/2012/08/27/discovering-the-value-in-discoverable-apis/ http://rtigger.com/blog/2012/08/27/discovering-the-value-in-... TL;DR - there's no value in discoverable (hypermedia) APIs short of some generic API browser that end users don't really want.

habitue 14y ago
While the library that browses arbitrary restful apis has to be generic, the applications built with that library, intending to interact with a specific API don't have to be generic
- RTigger 14y ago
  I suppose that's a good point. Once we have a standard in place (like the one proposed in the original article) it'd be relatively easy to make a client library that standardizes access to those kinds of API. You know, like WSDL used to do.
bct 14y ago
You lept to a conclusion here: > I think the original idea behind discoverability was that you could have a “RESTful client” that could in theory work with any REST service that implemented discoverability. Your analysis of that conclusion makes sense (a generic API browser is not very useful), but why did you think that's "the original idea behind discoverability"? The BitNative article you link to gives the reason that is usually cited for using hypermedia: > This allows the API to be highly evolvable because it avoids creating a coupling between the client and the server. Even more important IMO is that it makes it easier for the many different parties to serve the same API.
- RTigger 14y ago
  I don't understand the coupling aspect. You're moving from one dependency (URIs) to another (implementation of discoverability). Until HATEOAS/discoverability/rest links themselves are a standard, you're just binding to the way that API decided to do it. And that in my mind is a much bigger dependency than a URI string.
  - steveklabnik 14y ago
    The coupling is removed because you both standardize on the message format: the media type. Think RSS: clients and servers are decoupled.
Ramone 14y ago
There are a benefits, but most people won't notice them without first actually using a hypermedia API. * It's self-documenting. Client developers can find all the endpoints just by clicking around (instead of reading mountains of docs). * Client apps don't need to keep a list of hard-coded urls for random access, removing one of the most brittle parts of client apps (they should know about rels of course, but those end up being easier to keep track of). Once you actually use an API like this, other APIs feel like they're in the stone age and how to do things with them seems like a continual guessing game. And it's still simple as hell -- remember it's just json with links. It's not like that requires a lot of extra effort.
- RTigger 14y ago
  Fair enough - I haven't actually used a hypermedia API (short of OData). I really can't see the documenting point though. Sure, you get a list of actions that you can perform, but you get those in a response object. Some people compare this to "intellisense documentation", but really it's more like having to decompile the library to figure out what's going on. You have to do something extra in order to figure out what the next step is, rather than just having it available. Also, I'm pretty sure any API that is currently "discoverable" probably also has a full suite of documentation. Why do the same thing twice? Not sure about other languages, but most of the client apps I make don't use hardcoded urls - they use a base API url, and then modifications for specific resources. The RestSharp library for C# is a great example of how this works, and even in javascript it's not hard to refactor things so they use a base url and append path & parameters based on the models you're working with. I'm not arguing the simplicity of it, although it would be more simple to implement if we agreed on a standard like in the original article. I'm just arguing the value.

by RTigger 14y ago

habitue 14y ago

While the library that browses arbitrary restful apis has to be generic, the applications built with that library, intending to interact with a specific API don't have to be generic

RTigger 14y ago
I suppose that's a good point. Once we have a standard in place (like the one proposed in the original article) it'd be relatively easy to make a client library that standardizes access to those kinds of API. You know, like WSDL used to do.

bct 14y ago

You lept to a conclusion here: > I think the original idea behind discoverability was that you could have a “RESTful client” that could in theory work with any REST service that implemented discoverability. Your analysis of that conclusion makes sense (a generic API browser is not very useful), but why did you think that's "the original idea behind discoverability"? The BitNative article you link to gives the reason that is usually cited for using hypermedia: > This allows the API to be highly evolvable because it avoids creating a coupling between the client and the server. Even more important IMO is that it makes it easier for the many different parties to serve the same API.

RTigger 14y ago
I don't understand the coupling aspect. You're moving from one dependency (URIs) to another (implementation of discoverability). Until HATEOAS/discoverability/rest links themselves are a standard, you're just binding to the way that API decided to do it. And that in my mind is a much bigger dependency than a URI string.
- steveklabnik 14y ago
  The coupling is removed because you both standardize on the message format: the media type. Think RSS: clients and servers are decoupled.

Ramone 14y ago

There are a benefits, but most people won't notice them without first actually using a hypermedia API. * It's self-documenting. Client developers can find all the endpoints just by clicking around (instead of reading mountains of docs). * Client apps don't need to keep a list of hard-coded urls for random access, removing one of the most brittle parts of client apps (they should know about rels of course, but those end up being easier to keep track of). Once you actually use an API like this, other APIs feel like they're in the stone age and how to do things with them seems like a continual guessing game. And it's still simple as hell -- remember it's just json with links. It's not like that requires a lot of extra effort.

RTigger 14y ago
Fair enough - I haven't actually used a hypermedia API (short of OData). I really can't see the documenting point though. Sure, you get a list of actions that you can perform, but you get those in a response object. Some people compare this to "intellisense documentation", but really it's more like having to decompile the library to figure out what's going on. You have to do something extra in order to figure out what the next step is, rather than just having it available. Also, I'm pretty sure any API that is currently "discoverable" probably also has a full suite of documentation. Why do the same thing twice? Not sure about other languages, but most of the client apps I make don't use hardcoded urls - they use a base API url, and then modifications for specific resources. The RestSharp library for C# is a great example of how this works, and even in javascript it's not hard to refactor things so they use a base url and append path & parameters based on the models you're working with. I'm not arguing the simplicity of it, although it would be more simple to implement if we agreed on a standard like in the original article. I'm just arguing the value.