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 -
>
>
>
>