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

Re: [rest-discuss] Link relations [was: A media type for case files, dossiers and documents]

Expand Messages
  • Kevin Duffey
    I get everything you are saying..finally thanks to a few of you that set me clear on this whole media-type issue. I am however having a hard time thinking
    Message 1 of 88 , Dec 2, 2010
      I get everything you are saying..finally thanks to a few of you that set me clear on this whole media-type issue.

      I am however having a hard time thinking about telling clients that they basically need to parse html to use my API. I much rather say "for /orders, you get this chunk of xml back with these potential elements.. parse it to get the data you need". Or in JSON. As I use Java/JAX-RS with Jersey, it handles automatically turning my objects into either xml or json, whatever the Accept header specifies. Anyway, for my own learning, it is good to know what you said, and it does make sense. However, it seems odd to me to return things in HTML as opposed to xml or json, when it's just chunks.. that is, a user places 100 orders over 3 months, then comes in and asks to see a history of orders. I return an xml chunk with their 100 orders and related info. That seems perfectly fine to provide in xml or json, allowing any client to parse the response as they see fit. I would obviously have some sort of api doc that would explain the response.

      I guess what I am grappling with is that for the most part, I would suspect most services like the one I am messing around with to learn, would be used by specific clients, not anyone and everyone out on the web. More so, I don't see anyone needing to use my particular bits of data I return for their own use.. that is, if I were to register a media type that represents a generic ordering document, that might make sense, but in my case, if I am building up a REST api for my specific little service, it doesn't seem like returning HTML would make any more sense than returning xml or json. I certainly can see if I was building my own web site, where I have some javascript make ajax requests and I return a chunk of HTML instead of XML or JSON, so that my own site consuming my API can benefit from having HTML directly, rather than xml or json then have to build up the html on the fly in the browser. But for say a mobile app that had a native client that allowed a user to log in and pull up their recent orders, a chunk of XML would fit well. HTML seems more difficult to have to parse and deal with.. at least the way I think. Again, if I were going to display it in a browser..maybe it's fine, but if I wanted to do something with the data before displaying it or maybe it's not a web browser at all, html seems out of place. That's just my opinion tho from the bits I've learned the past few days.

      --- On Thu, 12/2/10, Eric J. Bowman <eric@...> wrote:

      From: Eric J. Bowman <eric@...>
      Subject: Re: [rest-discuss] Link relations [was: A media type for case files, dossiers and documents]
      To: "Kevin Duffey" <andjarnic@...>
      Cc: "Rest Discussion List" <rest-discuss@yahoogroups.com>, juergen.brendel@...
      Date: Thursday, December 2, 2010, 10:32 PM


      Kevin Duffey wrote:
      > Valid point. I am not sure what media type would fit then. I am
      > trying to follow the HATEOS design, I have an entry point that
      > returns some links based on credentials, from there a client would
      > use those to make calls to any of my resources, and each response
      > would return a relevant chunk of XML or JSON with links for each
      > resource accessible at that point (for example GET /orders/id would
      > return a specific order along with one or more links that can be used
      > to operate on the order).

      I've never seen an order-processing system that couldn't be modeled as
      HTML. In fact, I've rarely seen an order-processing system that wasn't
      HTML. In OOP terminology, the goal is to distribute not your objects,
      but your object interfaces. REST says, make those object interfaces
      uniform. Which means participants have a network-based shared
      understanding of your state transitions (links, forms), IOW, a self-
      documenting API.

      It's perfectly acceptable to model your data as JSON or as XML (bearing
      in mind that schemas are an orthogonal concern). The trick is to
      create an HTML interface for either JSON or XML data, which instructs
      user-agents how to interact with that data. I'd choose either JSON or
      XML, instead of trying to do both, depending on whether you're more
      comfortable transforming that data into HTML using Javascript or XSLT.

      > So if I use application/xml, my API would not be considered truly
      > RESTful?

      No, not if you're using application/xml as the hypertext engine driving
      application state. If it's just a snippet of XML which gets read by,
      say, an HTML front-end driving application state, then it's OK because
      the processing model (parse as XML, handling XInclude/XLink/rdf:about)
      is adequate to the task. If that XML snippet contains URIs the user is
      supposed to click on to transition the application to the next steady-
      state (which aren't XLinks), well, that's what <a> and atom:link are
      for, there's no corollary in application/xml (besides XLink).

      Also, most order forms are simply tabular data, the semantics of which
      don't exist in application/xml like they do in application/xhtml+xml or
      text/html with <table>. Same with lists, same with forms.

      > So now I'll ask, what media type I could possibly use with my own
      > xml/json structure? It almost sounds like you're saying I shouldn't
      > be returning my own made up structure, that I should instead use an
      > existing media type, like one with xhtml or something. Is there a
      > media type that allows for any sort of specific format to a domain to
      > be returned? Or does that now fall into a case where I should create
      > my own media type and register it with IANA?

      It falls into a case where you should refactor. You have tabular data,
      so you need to choose a data type which expresses such semantics (i.e.
      HTML, or DocBook). The whole point of media types is that they are
      _not_ domain-specific, but rather, represent a shared understanding of
      a processing model at the network (IP) layer. This is the fundamental
      tradeoff of the style:

      "[A] uniform interface degrades efficiency, since information is
      transferred in a standardized form rather than one which is specific to
      an application's needs."

      An order consists of item numbers, descriptions, quantity, unit price
      and total price. You *could* re-invent the <table> wheel and register
      it as a new media type, but it's more scalable (maintainable, portable)
      to re-use HTML even if it isn't a precise fit. If you create a new
      media type, then you need to distribute a custom user-agent. When you
      upgrade your API, you must simultaneously update that user-agent.

      The success of the Web is due to the common user-agent. What I really
      don't want, is for any system I interact with to require me to install
      yet another piece of software, and keep it up-to-date. That's coupling.
      So much easier for everyone concerned, to target the browser. That way,
      I only need to install and maintain one user-agent regardless of how
      many different systems I interact with. Such decoupling allows clients
      and servers to evolve independently. So there is a cost associated
      with the minting of new media types -- coupling -- unless and until the
      new media type achieves significant uptake.


    • Peter Williams
      On Sun, Dec 5, 2010 at 5:12 PM, Eric J. Bowman wrote: ... I see in table 5-1[1] media type is listed in the modern web
      Message 88 of 88 , Dec 5, 2010
        On Sun, Dec 5, 2010 at 5:12 PM, Eric J. Bowman <eric@...> wrote:


        > Anyway, it was previously discussed that the sentence in question is a
        > bit buggy, which is in part to blame for the confusion.  REST can be
        > instantiated over IP by any protocol using media types, and meeting the
        > other constraints like caching, not just by HTTP.  But the media type
        > is the means by which resource and representation are decoupled.

        I see in table 5-1[1] "media type" is listed in the modern web
        examples column. That does seem to bolster your argument. However,
        the dissertation uses the term while describing the style rather than
        http specifically. Your interpretation would seem to imply that a
        stack (networking system and restful application protocol) that
        eschewed iana registered media types would have to have to use a
        different term for "the flavor of representations".

        Perhaps it is a bug that the dissertation uses "media type" in the way
        it does. However, that cannot be undone. Given that the dissertation
        does use the term the way it does i stand by my assertion that there
        are two valid uses of "media type". One which means a data format
        that is registered with iana, and another that means a type, defined
        by a specification, of representation used in a restful system.

        Regardless, it seems a point of little importance.

        [1]: <http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#tab_5_1>

      Your message has been successfully submitted and would be delivered to recipients shortly.