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

Message Payloads

Expand Messages
  • albertwylde
    I am somewhat new to the REST architectural style, so please go easy on me. I am having difficulty understanding how a machine agent would understand the
    Message 1 of 4 , Jun 6, 2011
      I am somewhat new to the REST architectural style, so please go easy on me. 

      I am having difficulty understanding how a machine agent would understand the content of my payload when using a generic media type.  I have been reading @mamund's latest presentation http://www.amundsen.com/talks/#more-rest  on how ROT is bad, and have lived the painful problems associated with changing elements in schemas in the past.  Problem is that I don't know how to create a "common understanding of the payloads passed between" client and server and my mind tends to go to the "how can the server successfully export its private objects in a way that clients can see and use them".  Need help understanding this concept further.

      My current thought process (please correct):

      I would like to return a list of entities from a search.  Atom could provide the list, but an agent will not understand my content payload without some a priori knowledge. 

      Lets say I have an entity "Person" with 3 elements: "name", "address", and  "age" with associated data types String, String, Int.  In the past, I would have created a schema that described this entity and passed this information inside a Collection element.  But this seems to cause problems down the line.  If I change this concept to something like:

      <items>
        <item href="http://example.com/5612315623156">
          <data name="name">Roy</data>
          <data name="address">12 Foobar St</data>
          <data name="age">31</data>
        </item>
      ...

      Given I would be using a generic media type ...
      How does the agent know it is a Person type? 
      How does the agent know what "name", "address", or "age" mean?

      Would I provide a namespace to the schema describing this entity?  A link relation?  I don't want to create "Object-Based Media Type ROT" by creating "application/myperson+xml".  I feel like I am missing something here.  Need help!!

    • Eric J. Bowman
      ... In REST, you re not exporting objects, but generic object interfaces. Any user-agent that understands your object interfaces (using ubiquitous media types,
      Message 2 of 4 , Jun 6, 2011
        >
        > "how can the server successfully export its private objects in a way
        > that clients can see and use them".
        >

        In REST, you're not exporting objects, but generic object interfaces.
        Any user-agent that understands your object interfaces (using ubiquitous
        media types, i.e. forms) can manipulate your objects whether it
        understands them or not. Making the (machine) user understand what the
        markup represents is a separate problem from REST, I suggest RDFa.

        -Eric
      • Jason Erickson
        Thanks for the link to his slides. I m trying to improve my understanding of REST in exactly this area myself lately. From my reading, Amundsen is NOT using a
        Message 3 of 4 , Jun 6, 2011
          Thanks for the link to his slides.  I'm trying to improve my understanding of REST in exactly this area myself lately.  

          From my reading, Amundsen is NOT using a generic type (such as application/xml) - he is using a vendor specific but well documented type: application/vnd.phactor+xml.  You can see the documentation here: http://amundsen.com/media-types/phactor/

          I don't know to what extent this is a real world media type or a sample of what a good one would look like, but it is definitely a vendor-specific media type.  To me, his slides are advocating for a looser coupling of clients and servers by defining the media type in terms of HOW you are going to relay information, not WHAT information you are sending/receiving.

          So, in the case of the maze example, every maze element is just a list of links that you could follow to another maze element.  Rather than define it in terms of 
          <maze><connectedNodes><maze id='m1'/><maze id='m2'/><maze id='m3'/></connectedNodes></maze>

          He defines it as
          <maze><collection href="http:/www.example/mazes"><link href="http://www.example.org/mazes/1" rel="maze" id="m1"/>...</collection></maze>

          Now, if you had a program that already understood the application/vnd.phactor+xml media type, it would be able to understand this quite well.  Of course, if you want to do something particularly "mazy" with it, you would have to understand specifically the media type of application/vnd.amundsen.maze+xml, but there's no getting around that I think.

          That's the way I read it, but as I said, I'm trying to get my head around this stuff, too, so I'd be interested in others' thoughts on this just like you.

          On Jun 6, 2011, at 10:54 AM, albertwylde wrote:

           

          I am somewhat new to the REST architectural style, so please go easy on me. 

          I am having difficulty understanding how a machine agent would understand the content of my payload when using a generic media type.  I have been reading @mamund's latest presentation http://www.amundsen.com/talks/#more-rest  on how ROT is bad, and have lived the painful problems associated with changing elements in schemas in the past.  Problem is that I don't know how to create a "common understanding of the payloads passed between" client and server and my mind tends to go to the "how can the server successfully export its private objects in a way that clients can see and use them".  Need help understanding this concept further.

          My current thought process (please correct):

          I would like to return a list of entities from a search.  Atom could provide the list, but an agent will not understand my content payload without some a priori knowledge. 

          Lets say I have an entity "Person" with 3 elements: "name", "address", and  "age" with associated data types String, String, Int.  In the past, I would have created a schema that described this entity and passed this information inside a Collection element.  But this seems to cause problems down the line.  If I change this concept to something like:

          <items>
            <item href="http://example.com/5612315623156">
              <data name="name">Roy</data>
              <data name="address">12 Foobar St</data>
              <data name="age">31</data>
            </item>
          ...

          Given I would be using a generic media type ...
          How does the agent know it is a Person type? 
          How does the agent know what "name", "address", or "age" mean?

          Would I provide a namespace to the schema describing this entity?  A link relation?  I don't want to create "Object-Based Media Type ROT" by creating "application/myperson+xml".  I feel like I am missing something here.  Need help!!


        • mike amundsen
          Jason/Albert: I posted a blog entry today[1] that addresses some of your remarks (from my POV only, of course ). the tl;dnr version is here: - The point of
          Message 4 of 4 , Jun 7, 2011
            Jason/Albert:

            I posted a blog entry today[1] that addresses some of your remarks (from my POV only, of course<g>).
            the tl;dnr version is here:

            - The point of the talk was to "jolt" attendees into thinking differently about common Web implementation details (e.g. type marshaling/object serialization)
            - The slides themselves are "prompts" for the presentation and are missing quite a few nuances/details (sorry, no recording is available).
            - Due to time constraints I left out example designs based on HTML (only used XML and JSON examples in the slides)
            - The bottom-line message of the talk was to create messages that include not just "what" (data), but also "how" (hypermedia).

            I'd be happy to discuss this further either here or at a list i recently started that is focused on Hypermedia [2]. You can email me directly, too, if you like.

            [2] https://groups.google.com/forum/#!forum/hypermedia-web
            mca
            http://amundsen.com/blog/
            http://twitter.com@mamund
            http://mamund.com/foaf.rdf#me


            #RESTFest 2011 - Aug 18-20
            http://restfest.org






            On Mon, Jun 6, 2011 at 15:47, Jason Erickson <jason@...> wrote:
            >
            >
            > Thanks for the link to his slides.  I'm trying to improve my understanding of REST in exactly this area myself lately.  
            > From my reading, Amundsen is NOT using a generic type (such as application/xml) - he is using a vendor specific but well documented type: application/vnd.phactor+xml.  You can see the documentation here: http://amundsen.com/media-types/phactor/
            > I don't know to what extent this is a real world media type or a sample of what a good one would look like, but it is definitely a vendor-specific media type.  To me, his slides are advocating for a looser coupling of clients and servers by defining the media type in terms of HOW you are going to relay information, not WHAT information you are sending/receiving.
            > So, in the case of the maze example, every maze element is just a list of links that you could follow to another maze element.  Rather than define it in terms of 
            > <maze><connectedNodes><maze id='m1'/><maze id='m2'/><maze id='m3'/></connectedNodes></maze>
            > He defines it as
            > <maze><collection href="http:/www.example/mazes"><link href="http://www.example.org/mazes/1" rel="maze" id="m1"/>...</collection></maze>
            > Now, if you had a program that already understood the application/vnd.phactor+xml media type, it would be able to understand this quite well.  Of course, if you want to do something particularly "mazy" with it, you would have to understand specifically the media type of application/vnd.amundsen.maze+xml, but there's no getting around that I think.
            > That's the way I read it, but as I said, I'm trying to get my head around this stuff, too, so I'd be interested in others' thoughts on this just like you.
            > On Jun 6, 2011, at 10:54 AM, albertwylde wrote:
            >
            >  
            >
            > I am somewhat new to the REST architectural style, so please go easy on me. 
            >
            > I am having difficulty understanding how a machine agent would understand the content of my payload when using a generic media type.  I have been reading @mamund's latest presentation http://www.amundsen.com/talks/#more-rest  on how ROT is bad, and have lived the painful problems associated with changing elements in schemas in the past.  Problem is that I don't know how to create a "common understanding of the payloads passed between" client and server and my mind tends to go to the "how can the server successfully export its private objects in a way that clients can see and use them".  Need help understanding this concept further.
            >
            > My current thought process (please correct):
            >
            > I would like to return a list of entities from a search.  Atom could provide the list, but an agent will not understand my content payload without some a priori knowledge. 
            >
            > Lets say I have an entity "Person" with 3 elements: "name", "address", and  "age" with associated data types String, String, Int.  In the past, I would have created a schema that described this entity and passed this information inside a Collection element.  But this seems to cause problems down the line.  If I change this concept to something like:
            >
            > <items>
            >   <item href="http://example.com/5612315623156">
            >     <data name="name">Roy</data>
            >     <data name="address">12 Foobar St</data>
            >     <data name="age">31</data>
            >   </item>
            > ...
            >
            > Given I would be using a generic media type ...
            > How does the agent know it is a Person type? 
            > How does the agent know what "name", "address", or "age" mean?
            >
            > Would I provide a namespace to the schema describing this entity?  A link relation?  I don't want to create "Object-Based Media Type ROT" by creating "application/myperson+xml".  I feel like I am missing something here.  Need help!!
            >
            >
            >
            >
            >
          Your message has been successfully submitted and would be delivered to recipients shortly.
          »
          «