Re: How much REST should your Web API get?

On 02.05.2013, at 21:15, Mike Schinkel <[email protected]> wrote:

> On May 2, 2013, at 2:34 PM, Jan Algermissen <[email protected]> wrote:
>> I'd say, the vast majority of Web APIs fails to be RESTful because people simply did not follow the style. Show me a single example that has been deliberately designed  unRESTful on the basis of design principles.
> 
> I think that last statement is demonstrably provable to be false. To make a web API purely RESTful takes more effort on the part of the client and some who have published web APIs have on purpose chosen not to require that effort. I can't point to specific APIs at this moment but I know I've read posts from others on various other web API-related lists such as API Craft saying that pure REST makes it harder than they want for people to succeed at using their web API.

It is true that REST achieves much of its decoupling by moving responsibilities to the client and it is also true that it requires more work on the client side compared to hard coding a bunch of URIs.

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.

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.

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

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

>   
> 
> Of course if they then call their web API RESTful they are in the wrong.
> 
> Further, and this (only) a slight tangent but the more I learn about pure REST the more I come to believe that the focus on hypermedia constraint it a red herring when an application-specific media type is not used.

Well, yes. Of course.

> AFAICT very promoting hypermedia make the explicit point that hypermedia does not bring the benefits of REST without a dedicated media type.

Yes, because generic media types only shove the problem up a layer - into out of band knowledge.

> By itself hypermedia just adds complexity; with a dedicated media-type a client can be built that "knows" what do with the links found in the media type

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


> but I see (almost?) nobody advocating this besides some cryptic comments from Roy on his blog almost 5 years ago.

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

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.

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

Jan


> 
> -Mike


[1] http://tools.ietf.org/html/draft-nottingham-json-home

------------------------------------

Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http://groups.yahoo.com/group/rest-discuss/

<*> Your email settings:
    Individual Email | Traditional

<*> To change settings online go to:
    http://groups.yahoo.com/group/rest-discuss/join
    (Yahoo! ID required)

<*> To change settings via email:
    [email protected] 
    [email protected]

<*> To unsubscribe from this group, send an email to:
    [email protected]

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.com/info/terms/