Re: How much REST should your Web API get?

Andrei,

Here is the excerpt from the REST dissertation, "5.1.2 Client - Server"
section:

"By separating the user interface concerns from the data storage concerns,
we improve the portability of the user interface across multiple platforms
and improve scalability by simplifying the server components"

Also section "5.3.3 Data view"

"The model application is therefore an engine that moves from one state to
the next by examining and choosing from among the alternative state
transitions in the current set of representations. Not surprisingly, this
exactly matches the user interface of a hypermedia browser."

I think the cause of misunderstanding is with what you call a "REST API",
which is probably not really/fully a REST API. Can you give me a concrete
example of a REST API (beside hypertext HTML/HTTP, hyperdata RDF/HTTP and
Atom/AtomPub)?

Best regards,
Jerome



2013/5/3 Andrei Neculau <[email protected]>

> Forgot to include the group, the first time.
>
> Jerome, thanks for your reply
>
> I cannot see where you're coming from though. Maybe can you provide a full
> excerpt where "it clearly states" what you say? To begin with, it makes
> little sense to read "a client is a .. UI"
> And I'm not the least convinced by the HTML&PDF vs JSON&XML argument.
> "user presentable" has nothing to do with this topic IMHO. Some media-types
> have document semantics, some don't. But it's the media-types that dictate
> the level of "is it user presentable?" and not the API style.
>
> Regarding mobility - I haven't got to that point yet, but I believe I will
> not have any issue building an app with local storage against a REST API.
> The reason I say it is that, when the server goes down, we're not talking
> about the same "app" anyways, no matter the style. Server is up, client
> follows what the server says, follows its affordances. Server is down,
> client follows a hardcoded/fallback affordances, and then later tries to
> reach state ~consistency and mitigate conflicts. How the sync is done, via
> following a special relation (e.g. offline-sync) or by following the normal
> links (i.e. replaying the local operations as remote operations) is again
> of no importance. Similar thing happens with a web API.
>
> Best of luck though. No need to convince me :)
>
>
>
> On Fri, May 3, 2013 at 3:55 PM, Jérôme Louvel <[email protected]> wrote:
>
>> Hi Andrei,
>>
>> If you read carefully the REST chapter in Roy's dissertation (or the
>> excerpts I took from it in the blog post), it clearly states that the
>> client is an hypermedia-based UI (or some sort of spider like a search
>> engine).
>>
>> Most of the use cases I see for web APIs are about communication between
>> a client machine (a program or a device) and an origin server (via
>> potential intermediaries). The immediate client isn't intended to be a
>> human because the web API requires manipulation of structured data via JSON
>> / XML representations instead of user presentable HTML/PDF representations.
>>
>> Even though you can use conneg to negotiate a UI friendly representation
>> of your resources (nice to have), you can't fully interact with the API
>> this way and there is no reason to do so as the UI is working at another
>> layer above or beyond (native app, HTML app doing AJAX calls, connected
>> device with physical buttons for example, speech2text UI such as for a call
>> center, etc.).
>>
>> Regarding the Mobility constraint/requirement, REST assumes that there is
>> a more or less constant connection between the client/UI and the server to
>> make the application work (HATEOAS). New mobile internet usage requires
>> mobile app developer to take this aspect of networking into account deep in
>> the design of the user interaction as well as the connection to the
>> backend. The idea is to have a local storage that is regularly synchronized
>> with the backend when internet connectivity is available again.
>>
>> Best regards,
>> Jerome
>>
>>
>>
>> 2013/5/3 [email protected] <[email protected]>
>>
>>> Jerome,
>>>
>>> 2 questions:
>>>
>>> - why are you highlighting that "the web api style" is driven by
>>> machine-to-machine interactions? Coupled with the comment from John
>>> Schlesinger, it hear that you put REST in the category of human-to-machine
>>> interactions. ?!
>>> - is "the mobility constraint" outside of REST? Some of the items there
>>> are simply server-should-optimize-by-sniffing, instead of
>>> client-should-optimize-given-it-has-the-whole-context.
>>>
>>> If I take out these 2, then the rest - coordinated evolution and custom
>>> interfaces - is something that shouldn't sound attractive to anyone.
>>>
>>> Otherwise, Jan did me justice all the way and I have nothing to add.
>>>
>>> Thanks
>>>
>>> --- In [email protected], "jerome.louvel" <jlouvel@...>
>>> wrote:
>>> >
>>> > After living with REST for 10 years and introducing in 2005 the first
>>> REST framework for Java (http://restlet.org), I felt that by pushing
>>> REST too far we are just trying to make it solve problems it was designed
>>> for in the first place.
>>> >
>>> > In this blog post, I tried to formalize a "Web API" architecture style
>>> and contrast it with REST, then introduce the idea of cross-device web
>>> sites as wrapping the power of both styles:
>>> >
>>> http://blog.restlet.com/2013/05/02/how-much-rest-should-your-web-api-get/
>>> >
>>> > Interested in hearing what you think!
>>> >
>>> > Best regards,
>>> > Jerome
>>> >
>>> > PS: sorry for those also following the "API-Craft" mailing list, but
>>> the topic is right at the crossing of both communities.
>>> >
>>>
>>>
>>>
>>
>
>
> --
> andreineculau.com <http://www.andreineculau.com> -- Emails should be five
> sentenc.es <http://five.sentenc.es> or less.
>
> The time spent on any item of the agenda will be in inverse proportion to
> the sum involved. *C. Northcote Parkinson*
> http://en.wikipedia.org/wiki/Parkinson's_Law_of_Triviality
>