3 ms·

Why, are external developers able to consume restful APIs without the need for any documentation on the system they're talking to? Aren't the various REST entit

by Udik 12y ago

Why, are external developers able to consume restful APIs without the need for any documentation on the system they're talking to? Aren't the various REST entities (and all the possible links between them, if you're doing HATEOAS) already part of a protocol the developers of external consumers need to know beforehand?

dragonwriter 12y ago
> Why, are external developers able to consume restful APIs without the need for any documentation on the system they're talking to? In a fully RESTful, an external developer would be able to consume it with only documentation of the resource types used, and identification of a single base URI for a known resource from which the rest of the API's locations were discoverable. (That doesn't mean that an API owner wouldn't still want to document more, but it wouldn't be strictly necessary.)
mbleigh 12y ago
I'm speaking from the experience of a developer who has built numerous public APIs and client libraries over the years. Yes, you still need documentation for a REST API (I'm not a HATEOAS utopian), but you can easily attach your documentation to concepts with which many (probably most) developers are already familiar. The article is basically saying "You know how lots of cars have steering wheels and pedals? Well, I think it's annoying to build cars that way, so I'm going to use a system of levers and buttons." There's a ton of utility in anchoring new systems to familiar concepts, and unless you have a good reason not to you should strive to do so.
- drinchev 12y ago
  I totally agree. That's my first argument against the idea of the OP. In these days you have out-of-the-box so many already working API clients and already so many public API End-points that it would be really, really hard to create some ( opinionated ) better way of doing this. Libraries like Backbone and platforms like NodeJS ( and many more ) have this idea so deep that it becomes extremely easy to create an API front-end / back-end app with just a matter of a couple of files ( even lines ). This is becoming standard in other platforms as well. I think the debate is long time shifted from "Is REST good for my app?" to "How to best follow RESTful principles in my app?"
a_c_s 12y ago
Sure, that sounds nice in theory. In the wild, how many developers (especially those working on internal APIs) have the time & inclination to thoroughly document their entire APIs? And if it exists, many developers read the entire spec of an API before beginning development? In my experience both are rare. Given the constraints developers often find themselves under, having an API that uses common patterns most developers already understand has great value. (Ex. 'GET /customer/123' performs a safe retrieval of a representation of the customer with ID 123, no documentation required) This leaves both developers (API creator & API consumer) free to focus on documenting/understanding the non-trivial parts of the API rather than reinventing the wheel.
- dragonwriter 12y ago
  Note that this use of conventional URI structure patterns does have the value you describe, but is also completely orthogonal to REST (REST isn't about beautiful URIs -- the path part of the URI could all be UUIDs and you could follow the REST architectural style perfectly; HATEOAS, in particular, means that other than the entry point, your URIs should all be coming to you from other documents with their context in that document telling you what they are, so you don't need to parse the URI for meaning.)
  - a_c_s 12y ago
    Yes, there is a difference betwixt 'true REST' (as defined by Roy Fielding in his PhD dissertation) and what most people refer to as REST. I was referring to the latter: in my experience 'true REST' APIs are rare in the wild.
doktrin 12y ago
He didn't say external developers wouldn't need any documentation to consume a REST API. The implication made was that developers are more accustomed to REST, hence REST is easier to consume. Speaking for myself, I've found this to be true.

by Udik 12y ago

dragonwriter 12y ago

> Why, are external developers able to consume restful APIs without the need for any documentation on the system they're talking to? In a fully RESTful, an external developer would be able to consume it with only documentation of the resource types used, and identification of a single base URI for a known resource from which the rest of the API's locations were discoverable. (That doesn't mean that an API owner wouldn't still want to document more, but it wouldn't be strictly necessary.)

mbleigh 12y ago

I'm speaking from the experience of a developer who has built numerous public APIs and client libraries over the years. Yes, you still need documentation for a REST API (I'm not a HATEOAS utopian), but you can easily attach your documentation to concepts with which many (probably most) developers are already familiar. The article is basically saying "You know how lots of cars have steering wheels and pedals? Well, I think it's annoying to build cars that way, so I'm going to use a system of levers and buttons." There's a ton of utility in anchoring new systems to familiar concepts, and unless you have a good reason not to you should strive to do so.

drinchev 12y ago
I totally agree. That's my first argument against the idea of the OP. In these days you have out-of-the-box so many already working API clients and already so many public API End-points that it would be really, really hard to create some ( opinionated ) better way of doing this. Libraries like Backbone and platforms like NodeJS ( and many more ) have this idea so deep that it becomes extremely easy to create an API front-end / back-end app with just a matter of a couple of files ( even lines ). This is becoming standard in other platforms as well. I think the debate is long time shifted from "Is REST good for my app?" to "How to best follow RESTful principles in my app?"

a_c_s 12y ago

Sure, that sounds nice in theory. In the wild, how many developers (especially those working on internal APIs) have the time & inclination to thoroughly document their entire APIs? And if it exists, many developers read the entire spec of an API before beginning development? In my experience both are rare. Given the constraints developers often find themselves under, having an API that uses common patterns most developers already understand has great value. (Ex. 'GET /customer/123' performs a safe retrieval of a representation of the customer with ID 123, no documentation required) This leaves both developers (API creator & API consumer) free to focus on documenting/understanding the non-trivial parts of the API rather than reinventing the wheel.

dragonwriter 12y ago
Note that this use of conventional URI structure patterns does have the value you describe, but is also completely orthogonal to REST (REST isn't about beautiful URIs -- the path part of the URI could all be UUIDs and you could follow the REST architectural style perfectly; HATEOAS, in particular, means that other than the entry point, your URIs should all be coming to you from other documents with their context in that document telling you what they are, so you don't need to parse the URI for meaning.)
- a_c_s 12y ago
  Yes, there is a difference betwixt 'true REST' (as defined by Roy Fielding in his PhD dissertation) and what most people refer to as REST. I was referring to the latter: in my experience 'true REST' APIs are rare in the wild.

doktrin 12y ago

He didn't say external developers wouldn't need any documentation to consume a REST API. The implication made was that developers are more accustomed to REST, hence REST is easier to consume. Speaking for myself, I've found this to be true.