Yeah, I'm going to disagree a bit with the original post in this thread, 
and with Richard's contribution too. Or at least qualify it.

My experience is that folks trying to be pure and avoid an API do _not_ 
make it easier for me to consume as a developer writing clients. It's 
just not true that one always leads to the other.

The easiest API's I have to deal with are those where the developers 
really understand the use cases clients are likely to have, and really 
make API's that conveniently serve those use cases.

The most difficult API's I have to deal with are those where the 
developers spent a lot of time thinking about very abstract and 
theoretical concerns of architectural purity, whether in terms of REST, 
linked data, HATEOS, or, god forbid, all of those and more at once (and 
then realizing that sometimes they seem to conflict) -- and neglected to 
think about actual use cases and making them smooth.

Seriously, think about the most pleasant, efficient, and powerful API's 
you have used.  (github's?  Something else?).  How many of them are 
'pure' non-API API's, how many of them are actually API's?

I'm going to call it an "API" even if it does what the original post 
says, I'm going to say "API" in the sense of "how software is meant to 
deal with this" -- in the base case, the so-called "API" can be "screen 
scrape HTML", okay.

I am going to agree that aligning the API with the user-visible web app 
as much as possible -- what the original post is saying you should 
always and only do -- does make sense.  But slavish devotion to avoiding 
any API as distinct from the human web UI at all leads to theoretically 
pure but difficult to use API's.

Sometimes the 'information architecture' that makes sense for humans 
differs from what makes sense for machine access. Sometimes the human UI 
needs lots of JS which complicates things.  Even without this, an API 
which lets me choose representations based on different URI's instead of 
_only_ conneg (say, "/widget/18.json" instead of only "/widget/18" with 
conneg) ends up being significantly easier to develop against and debug.

Spend a bit of time understanding what people consider theoretically 
pure, sure, because it can give you more tools in your toolbox.  But 
simply slavishly sticking to it does not, in my experience, result in a 
good 'developer experience' for your developer clients.  And when you 
start realizing that different people from different schools have 
different ideas of what 'theoretically pure' looks like, when you start 
spending many hours going over "HTTP RANGE 14" and just getting more 
confused -- realize that what matters in the end is being easy to use 
for your developers use cases, and just do it.

Personally, I'd spend more time making sure i understand my developers
use cases and getting feedback from developers, and less time on 
architecting castles in the sky that are theoretically pure.

On 12/2/13 9:56 AM, Bill Dueber wrote:
> On Sun, Dec 1, 2013 at 7:57 PM, Barnes, Hugh <[log in to unmask]>wrote:
>
>> +1 to all of Richard's points here. Making something easier for you to
>> develop is no justification for making it harder to consume or deviating
>> from well supported standards.
>
>
>
> ​I just want to point out that as much as we all really, *really* want
> "easy to consume" and "following the standards" to be the same
> thing....they're not. Correct content negotiation is one of those things
> that often follows the phrase "all they have to do...", which is always a
> red flag, as in  "Why give the user  different URLs ​when *all they have to
> do is*...". Caching, json vs javascript vs jsonp, etc. all make this
> harder. If *all * *I have to do* is know that all the consumers of my data
> are going to do content negotiation right, and then I need to get deep into
> the guts of my caching mechanism, then set up an environment where it's all
> easy to test...well, it's harder.
>
> And don't tell me how lazy I am until you invent a day with a lot more
> hours. I'm sick of people telling me I'm lazy because I'm not pure. I
> expose APIs (which have their own share of problems, of course) because I
> want them to be *useful* and *used. *
>
>    -Bill, apparently feeling a little bitter this morning -
>
>
>
>