Re: How much REST should your Web API get?

On May 2, 2013, at 3:39 PM, Jan Algermissen <[email protected]> wrote:
> However, the client developer also benefits from not being bothered with having to follow API updates *at all* (aside from long-term deprecation periods). It is a matter of trade off and I don;t think that the average client developer/owner would not understand what the flexibility buys them.

No disagreement there, I think on this list that's a given "known."  I also agree that it's a trade off and that many don't understand the distinction.  But I strongly think there are those who do understand and make the choice consciously, that way my only point in that paragraph.

> As always, REST is great for leveraging homogeneity and we should ease client developer's live by working much more intensly on things like JSON-Home[1]. Open source libs for these things should make arguments regarding client-developer ease irrelevant.

Agreed. The lack of standardization and available libs is what make hypermedia difficult.  15 years ago HTTP was difficult on some platforms (Microsoft's ASP for one example, earlier than that on Windows itself), but today HTTP is available in every developer tool there is. Hopefully time will march forward and bring similar improvement related to REST.

> Besides, the same people that talk about client-developer ease vs. REST today where the ones that sold you WS-* yesterday. I mean, what is a little form processing compared to getting a SOAP stack up an running :-)

heh.  Totally agree. :)

> IMHO, it is much more a matter of eductaion than a matter of developer ease.

eh, I think those are orthogonal issues.

> Yes, because generic media types only shove the problem up a layer - into out of band knowledge.
> User agents *implement* media type specifications. And they offer users to activate controls to proceed from one steady state to the next through *their* application.

Exactly.

> I do and others, too. I also apply specific media types in real world projects with great satisfaction and no pain on neither side.

I guess I should clarify, I don't read a lot of blog posts on well known blogs on REST about this specific issue. I do occasional see side comments in list threads, but can't remember a single list thread devoted to the topic.  

When I get around to it I might blog about it, but my then blog is not "well known." :)

> It's just that its very difficult to argue about (and it's all there in the archives and on Roy's blog :-) anyhow) but much easier to demonstrate with a real problem at hand.

Agreed.

> It's also pretty straight forward, actually. I have never understood the reluctance people have to put they semantics they need done in a media type - right where REST wants them to be. <shrug/>

I disagree that it is "easy."  Building a good media type takes a lot of architecture skill (IMO) to get it right, without requiring constant and ongoing revisions which pretty much moots the benefit.

Also (IMO) I don't think there is a real value unless the media type is shared by a lot of users (which also argues against media type proliferation.) For example if FreshBooks, Wave, Xero, Kashoo, Outright, FreeAgent, Harvest etc. each were to all create their own media type for their own web APIs they would not provide much value over hardcoded URLs. OTOH if they all got together and created an "application/accounting" media type then I could see huge benefit.  (Hmm.  Maybe there is something there...)

-Mike