Loading ...
Sorry, an error occurred while loading the content.

Re: How much REST should your Web API get?

Expand Messages
  • Jérôme Louvel
    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
    Message 1 of 46 , May 3, 2013

      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,

      2013/5/3 Andrei Neculau <andrei.neculau@...>
      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 <jlouvel@...> 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,

      2013/5/3 andrei.neculau@... <andrei.neculau@...>

      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.


      --- In rest-discuss@yahoogroups.com, "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 -- Emails should be 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

    • Mike Schinkel
      Once again you have given me much to ponder. Thanks for the effort; I will be trying to internalize this. -Mike
      Message 46 of 46 , May 4, 2013
        Once again you have given me much to ponder. Thanks for the effort; I will be trying to internalize this.


        On May 4, 2013, at 1:49 PM, "Markus Lanthaler" <markus.lanthaler@...> wrote:

        > On Saturday, May 04, 2013 7:03 PM, Mike Schinkel wrote:
        >> Hmm. Okay, the more I think I understand about REST the more I think
        >> I don't understand and/or am unsure who actually really understands
        >> REST besides Roy.
        >> As I've read Roy I've come away understanding that messages must be
        >> self-contained
        > No, you are confusing self-contained with self-descriptive.
        >> and the only thing the client should know is how the
        >> links in the returned representation are defined to behave as defined
        >> by the representation's content yype. Having links in one document and
        >> data in a second document where you have to have the contents of both
        >> documents seems to me to violate that need for self-containment.
        > ... if there would be a self-containment constraint that would be true --
        > but there isn't.
        >> I do have one question; if there is a home document that is cacheable
        >> for some period "X" and at the time immediately after an API client
        >> retrieves the home document the servers are moved and the client later
        >> perform an operation that requires URLs from the home document but
        >> before "X" time has passed, it can cause failure. If the message is
        >> self-contained that time window is greatly reduced. This is one of the
        >> reasons I can postulate there is a need for self-contained messages.
        > That doesn't matter at all. Program defensively, detect the error, and
        > recover.
        > I could just as well argue that separating them allows you to request them
        > in parallel which would probably be faster so the time window you are
        > talking about would be reduced even further.
        > --
        > Markus Lanthaler
        > @markuslanthaler
      Your message has been successfully submitted and would be delivered to recipients shortly.