> You simply cannot build a useful API client application without deep knowledge of the problem domain and the interface part of API. You're going to have API documentation and you're going to have to read it.
That has nothing to do with HATEOAS. Of course you have to know the interface part of the API, but the interface part is the content types. Not the Content-Type, though they can match, but the content types: the shape and structure of the documents you get from the service, and send to it. And those content types tell you, among other things, where to get or send other types.
> Besides, you need to know which "rel" to lookup
Sure, see above, that's part of the content types which the consumer needs to know in any case.
> And this all breaks down yet again when you get to offline support. If you've got a web app which is going to deal with not-yet-saved objects, you're back to being unable to compare URLs, or constructing them.
I fail to see the issue. You know the data you need to send to the service, and you know the content types to traverse in order to reach where to send your data in the service. What is the issue?
> Lastly, while I like working with clean URLs
URL shape has nothing whatsoever to do with REST.
> I dislike the ad-hoc specifications necessary to build real applications.
Why would they be any more ad-hoc than with any other interface standard?
I'm not following anything you've said about "content types". The well-defined, well-known content types in typical applications are images and other "attachment" type resources, as well as the occasional RSS feed or something like that.
In domain-specific APIs (ie. nearly all the ones that matter), every single resource type has a unique schema. Ignoring versioning, I can request resources with a specific URL pattern and parse them with specific logic. That's all there is to it. It's not complicated. The Content-Type is entirely irrelevant, unless I decide to use it for versioning or waste my time supporting both XML and JSON.
> > Stop the pontificating and get back to work.
> Oh irony, you're so delicious.
My point was directed at the whole "What is RESTful?" debate, including all the versioning, content types, URLs, headers, verbs, etc. Discussions of approaches and problems is not pontification. Discussion of "Which approach is more RESTful?" is pontification.
What bugs me about adding contents, strange result codes, and all of these things that "are in the spec even if they're only implemented sporadically" is that it's programming as if interoperability didn't matter.
It's almost as bad as the SOAP implementation in ASP.NET.
> I'm not following anything you've said about "content types".
Which amply demonstrates your complete lack of understanding of the subject "pontificate" about.
edit: you can downvote me all you want, does not change that fact. Here's what Fieldings has to say on the subject:
> A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types).
(I used "content types" for his "media types", that's about it).
That has nothing to do with HATEOAS. Of course you have to know the interface part of the API, but the interface part is the content types. Not the Content-Type, though they can match, but the content types: the shape and structure of the documents you get from the service, and send to it. And those content types tell you, among other things, where to get or send other types.
> Besides, you need to know which "rel" to lookup
Sure, see above, that's part of the content types which the consumer needs to know in any case.
> And this all breaks down yet again when you get to offline support. If you've got a web app which is going to deal with not-yet-saved objects, you're back to being unable to compare URLs, or constructing them.
I fail to see the issue. You know the data you need to send to the service, and you know the content types to traverse in order to reach where to send your data in the service. What is the issue?
> Lastly, while I like working with clean URLs
URL shape has nothing whatsoever to do with REST.
> I dislike the ad-hoc specifications necessary to build real applications.
Why would they be any more ad-hoc than with any other interface standard?
> Stop the pontificating and get back to work.
Oh irony, you're so delicious.