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