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

Fwd: Initial draft spec of HAL

Expand Messages
  • Mike Kelly
    I ve now produced an initial draft of a spec for a minimalist, generic media type. Love to get some feedback + pointers on this Cheers, Mike ... From: Mike
    Message 1 of 14 , Jun 14, 2011
    • 0 Attachment
      I've now produced an initial draft of a spec for a minimalist, generic
      media type.

      Love to get some feedback + pointers on this

      Cheers,
      Mike

      ---------- Forwarded message ----------
      From: Mike Kelly <mikekelly321@...>
      Date: Tue, Jun 14, 2011 at 5:01 PM
      Subject: Initial draft spec of HAL
      To: hal-discuss@...


      Hey,
      I published an initial draft for HAL here:
      http://stateless.co/hal_specification.html

      All thoughts/corrections/additions welcome!
      Cheers,
      Mike
    • mike amundsen
      Mike: Good to see this posted. I have just a few general comments/questions... 1) It might help to offer a number of examples of valid HAL representations
      Message 2 of 14 , Jun 14, 2011
      • 0 Attachment
        Mike:

        Good to see this posted.

        I have just a few general comments/questions...

        1) It might help to offer a number of examples of "valid" HAL representations (e.g. minimum valid response, typical, etc.)
        For example, AFAICT, <resource rel="self" href="..." /> is the minimal valid response, right? I assume responses that are nothing more than a set to resource and link elements is valid. However, your example shows a representation with serveral other elements (created_at, name, age, etc.). It might help to have some narrative that explains that any and all elements/attributes are legal as long as they do not conflict w/ the details of resource and link as you define here.

        2) You show resources w/ embedded content (@rel="td:item", etc.). These also have an @href, sometimes an @type. Do you need any MUST/SHOULD/MAY text regarding the relationship between the resource found at the other end of the @href and the one embedded in the document? IOW, are they both the same resource? the same content? or can the embedded content be unrelated to, or a summary of, the content found when deferencing the @href? does the @type only apply to the embedded content, or does it also act as a hint or constraint on the @href?

        3) Does is make sense to address Extensibility at all? IOW, can I (as a document author) extended the link and resource elements? can I modify the MUST/SHOULD/MAY status of any of the defined elements/attributes?

        4) You might consider adding a "version='1.0'" to root element (in case the schema changes over time).

        5) You use "Required" and "Optional" when describing the attributes of Link and Resource. Are these actually RFC2119 words (e.g. REQUIRED, OPTIONAL)?

        6) The doc sez: "The @name attribute MUST NOT be used to identify elements within a HAL representation." It's not clear why (to me). Will this break something? it is really a MUST and not a SHOULD?  

        7) Should you refer to definitions of the valid values for the attributes @href, @rel, @name, and @type? For example most defs of @rel allow this to be a set of tokens separated by spaces. Is that true for this media type, too? 

        8) You mention URI template, but have no other references to it. Maybe add a link to the ID?

        As you can see, I am getting into pretty small 'nits' here. Hopefully my feedback is helpful, tho.


        mca
        http://amundsen.com/blog/
        http://twitter.com@mamund
        http://mamund.com/foaf.rdf#me


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


        On Tue, Jun 14, 2011 at 12:17, Mike Kelly <mike@...> wrote:
        I've now produced an initial draft of a spec for a minimalist, generic
        media type.

        Love to get some feedback + pointers on this

        Cheers,
        Mike

        ---------- Forwarded message ----------
        From: Mike Kelly <mikekelly321@...>
        Date: Tue, Jun 14, 2011 at 5:01 PM
        Subject: Initial draft spec of HAL
        To: hal-discuss@...


        Hey,
        I published an initial draft for HAL here:
        http://stateless.co/hal_specification.html

        All thoughts/corrections/additions welcome!
        Cheers,
        Mike

        --
        You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
        To post to this group, send email to hypermedia-web@....
        To unsubscribe from this group, send email to hypermedia-web+unsubscribe@....
        For more options, visit this group at http://groups.google.com/group/hypermedia-web?hl=en.


      • Mike Kelly
        Hey mike Comments inline + I added the JSON variant and changed a bunch of stuff so might be worth another look today! ... I dropped the rel= self as it was
        Message 3 of 14 , Jun 15, 2011
        • 0 Attachment
          Hey mike

          Comments inline + I added the JSON variant and changed a bunch of stuff so might be worth another look today! 

          On Tue, Jun 14, 2011 at 8:44 PM, mike amundsen <mamund@...> wrote:
          Mike:

          Good to see this posted.

          I have just a few general comments/questions...

          1) It might help to offer a number of examples of "valid" HAL representations (e.g. minimum valid response, typical, etc.)
          For example, AFAICT, <resource rel="self" href="..." /> is the minimal valid response, right?

          I dropped the rel="self" as it was basically redundant. Minimum valid response is now <resource href="..." /> or { "@href": "..." } http://stateless.co/hal_specification.html#minimum
            
          However, your example shows a representation with serveral other elements (created_at, name, age, etc.). It might help to have some narrative that explains that any and all elements/attributes are legal as long as they do not conflict w/ the details of resource and link as you define here.

          Updated general description and constraints sections to include this
           

          2) You show resources w/ embedded content (@rel="td:item", etc.). These also have an @href, sometimes an @type. Do you need any MUST/SHOULD/MAY text regarding the relationship between the resource found at the other end of the @href and the one embedded in the document? IOW, are they both the same resource? the same content? or can the embedded content be unrelated to, or a summary of, the content found when deferencing the @href?

          Clarified under 'Resource Attributes' under @href definition
           

          3) Does is make sense to address Extensibility at all? IOW, can I (as a document author) extended the link and resource elements? can I modify the MUST/SHOULD/MAY status of any of the defined elements/attributes?

          Yes it does, thanks for reminding me: http://stateless.co/hal_specification.html#extending
           

          4) You might consider adding a "version='1.0'" to root element (in case the schema changes over time).

          I'm not sold on versioning, and if I was going to do it I would probably implement it as a parameter on the media type identifier rather than in the entity body to keep it visible without introspection.
           

          5) You use "Required" and "Optional" when describing the attributes of Link and Resource. Are these actually RFC2119 words (e.g. REQUIRED, OPTIONAL)?

          Yep, thanks
           

          6) The doc sez: "The @name attribute MUST NOT be used to identify elements within a HAL representation." It's not clear why (to me). Will this break something? it is really a MUST and not a SHOULD? 

          Fair enough, I changed it to avoid confusion. I used that wording to try and make it obvious it is not intended to be used like @id is in HTML. 
           

          7) Should you refer to definitions of the valid values for the attributes @href, @rel, @name, and @type? For example most defs of @rel allow this to be a set of tokens separated by spaces. Is that true for this media type, too?

          Sure, does anyone have any suggestions/preference on where to take these from?
           

          8) You mention URI template, but have no other references to it. Maybe add a link to the ID?

          Done 
           

          As you can see, I am getting into pretty small 'nits' here. Hopefully my feedback is helpful, tho.


          Definitely, thanks a lot for your input.

          Cheers,
          Mike
           

          mca
          http://amundsen.com/blog/
          http://twitter.com@mamund
          http://mamund.com/foaf.rdf#me


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


          On Tue, Jun 14, 2011 at 12:17, Mike Kelly <mike@...> wrote:
          I've now produced an initial draft of a spec for a minimalist, generic
          media type.

          Love to get some feedback + pointers on this

          Cheers,
          Mike

          ---------- Forwarded message ----------
          From: Mike Kelly <mikekelly321@...>
          Date: Tue, Jun 14, 2011 at 5:01 PM
          Subject: Initial draft spec of HAL
          To: hal-discuss@...


          Hey,
          I published an initial draft for HAL here:
          http://stateless.co/hal_specification.html

          All thoughts/corrections/additions welcome!
          Cheers,
          Mike

          --
          You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
          To post to this group, send email to hypermedia-web@....
          To unsubscribe from this group, send email to hypermedia-web+unsubscribe@....
          For more options, visit this group at http://groups.google.com/group/hypermedia-web?hl=en.


          --
          You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
          To post to this group, send email to hypermedia-web@....
          To unsubscribe from this group, send email to hypermedia-web+unsubscribe@....
          For more options, visit this group at http://groups.google.com/group/hypermedia-web?hl=en.


        • Mark Baker
          Interesting. Looks a lot like Atom, RDF, and even HTML if you squint a bit. I don t think that s a coincidence. Mark.
          Message 4 of 14 , Jun 15, 2011
          • 0 Attachment
            Interesting. Looks a lot like Atom, RDF, and even HTML if you squint a
            bit. I don't think that's a coincidence.

            Mark.
          • Mike Kelly
            You re right, it s not. Hopefully it s unique and practical enough to avoid being pointless! The main drivers were simplicity and encouraging applications to
            Message 5 of 14 , Jun 15, 2011
            • 0 Attachment
              You're right, it's not. Hopefully it's unique and practical enough to avoid being pointless! The main drivers were simplicity and encouraging applications to be expressed in terms of link relations. 

              Cheers,
              Mike

              On Wed, Jun 15, 2011 at 7:00 PM, Mark Baker <distobj@...> wrote:
              Interesting. Looks a lot like Atom, RDF, and even HTML if you squint a
              bit.  I don't think that's a coincidence.

              Mark.

            • Jason Erickson
              I actually prefer the rel= self as it makes @rel REQUIRED instead of usually required. I guess removing it simplifies the resource slightly at the expense of
              Message 6 of 14 , Jun 15, 2011
              • 0 Attachment
                I actually prefer the rel='self' as it makes @rel REQUIRED instead of usually required.  I guess removing it simplifies the resource slightly at the expense of extra explaining in the HAL spec.  For me, the less explanation required the better.

                Also, you have a typo in your XML example - the td:attachment resource is closed twice.

                On Jun 15, 2011, at 10:02 AM, Mike Kelly wrote:


                I dropped the rel="self" as it was basically redundant. Minimum valid response is now <resource href="..." /> or { "@href": "..." } http://stateless.co/hal_specification.html#minimum

              • Mike Kelly
                ... I m actually not too fussed either way, if there s a general consensus on that let s just change it back ... nice one, thanks :) Cheers, Mike
                Message 7 of 14 , Jun 15, 2011
                • 0 Attachment
                  On Wed, Jun 15, 2011 at 9:02 PM, Jason Erickson <jason@...> wrote:
                  I actually prefer the rel='self' as it makes @rel REQUIRED instead of usually required.  I guess removing it simplifies the resource slightly at the expense of extra explaining in the HAL spec.  For me, the less explanation required the better.

                  I'm actually not too fussed either way, if there's a general consensus on that let's just change it back
                   

                  Also, you have a typo in your XML example - the td:attachment resource is closed twice.

                  nice one, thanks :)

                  Cheers,
                  Mike
                   


                  On Jun 15, 2011, at 10:02 AM, Mike Kelly wrote:


                  I dropped the rel="self" as it was basically redundant. Minimum valid response is now <resource href="..." /> or { "@href": "..." } http://stateless.co/hal_specification.html#minimum

                  --
                  You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
                  To post to this group, send email to hypermedia-web@....
                  To unsubscribe from this group, send email to hypermedia-web+unsubscribe@....
                  For more options, visit this group at http://groups.google.com/group/hypermedia-web?hl=en.

                • Jason Erickson
                  I quite like the idea of in-band control because I like a developer to be able to look at a response and understand all of the transitions without necessarily
                  Message 8 of 14 , Jun 15, 2011
                  • 0 Attachment
                    I quite like the idea of in-band control because I like a developer to be able to look at a response and understand all of the transitions without necessarily having to go look at the documentation.  However let's not let my personal preference overly prescribe how people use HAL.

                    It seems like your (proposed?) control element could be modified slightly to allow inline templating and then those that like to give lots of in-band information would be able to do so.  So you could have something like:

                    <resource href="/" xmlns:ex="http://example.org/rels/">
                    <link rel="ex:basic" href="/bleh" />
                    <link rel="ex:search" href="/search_for;{searchTerm}" />
                    <control rel="ex:widgetate" href="/widget/{newID}" method="PUT"
                    content-type="application/x-www-form-urlencoded" template-type="application/x-www-form-urlencoded">
                    <input name="name" type="text" value="Already Existing Widget"/>
                    <select name="type">
                    <option value="ESSENTIAL" />
                    <option value="USEFUL" selected="true"/>
                    <option value="USELESS" />
                    </select>
                    </control>
                    <resource rel="ex:member" href="/foo">
                    <link rel="ex:created_by" href="/some_dude" />
                    <example>bar</example>
                    <resource rel="ex:status" href="/foo?status">
                    <status>disabled</status>
                    </resource>
                    </resource>
                    </resource>
                    Then, the in-band people like me are satisfied, but it's still generic enough to support whatever other content-types can be conceived of and of course, you can still have the @template to specify out-of-band if you prefer.  

                    Note, in the above example, if the valid choices for type of widget is dynamic, then in-band is the only practical way (that I can think of) to express that in a template.

                    Also, while forms have the advantage of being well understood, if having your stuff in-band is really the goal and you'd rather use JSON (or some other format), then inlining your template would also allow:

                    <resource href="/" xmlns:ex="http://example.org/rels/">
                    <link rel="ex:basic" href="/bleh" />
                    <link rel="ex:search" href="/search_for;{searchTerm}" />
                    <control rel="ex:widgetate" href="/widget/{newID}" method="PUT"
                    content-type="application/json" >
                    <![CDATA[
                    {
                      "name":"{{name}}",
                      "type":"{{type}}"
                    }
                    ]]>
                    </control>
                    <resource rel="ex:member" href="/foo">
                    <link rel="ex:created_by" href="/some_dude" />
                    <example>bar</example>
                    <resource rel="ex:status" href="/foo?status">
                    <status>disabled</status>
                    </resource>
                    </resource>
                    </resource>


                    On Jun 15, 2011, at 2:45 PM, Mike Kelly wrote:


                    On Wed, Jun 15, 2011 at 10:11 PM, Solomon Duskis <sduskis@...> wrote:
                    On Wed, Jun 15, 2011 at 3:51 PM, Mike Kelly <mike@...> wrote:
                    I actually thought about adding form-like/templated write to HAL. The problem is that it adds quite a lot of complexity and I'm still not convinced it's terribly useful. So instead I'm going to create a separate media type which just extends it to add this capability. Here's an example of what that could look like : https://gist.github.com/893552

                    Interesting...  but wouldn't good ol' form data work for most <control> cases?  Is there a way to KISS and have only marginal complexity addition?

                    Well that wouldn't be generic, and would significantly limit the number of existing resources on the web that the requests could be directed at.  
                     
                     
                    Also; you could actually define restbucks as an application that's "just" driven by link relations and express that with HAL. The app would lose any in-band dynamism you would expect from the use of form-like controls though.
                     
                    It would require "just" link relations and "just" minor out-of-band information (mostly methods, some message structure data as well).  Is that what you mean by losing "in-band dynamis?

                    Yes, some people consider this application design lacking. Personally, I'm quite happy to use link relations this way - hence why form-like stuff is left out of HAL and will be introduced as part of a separate type.

                    Cheers,
                    Mike

                    --
                    You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
                    To post to this group, send email to hypermedia-web@....
                    To unsubscribe from this group, send email to hypermedia-web+unsubscribe@....
                    For more options, visit this group at http://groups.google.com/group/hypermedia-web?hl=en.

                  • Mike Kelly
                    I think what your proposing here is to bring the template/form in-line , rather than in-band . From my pov, both template (i.e. linked or in-line) approaches
                    Message 9 of 14 , Jun 16, 2011
                    • 0 Attachment
                      I think what your proposing here is to bring the template/form 'in-line', rather than 'in-band'. From my pov, both template (i.e. linked or in-line) approaches bring the control in-band, as opposed to 'heavily typed links' where the control is out-of-band [1].

                      Regardless, it definitely makes a lot of sense to provide the option for the template itself to be placed in-line. Thanks for bringing that up.

                      One small gripe with your in-line example is the use of @template-type.. this should be a URI that identifies the template/form type you are using i.e. in the first example its value should be something like "http://www.w3.org/TR/html401/interact/forms"


                      Cheers,
                      Mike 

                      On Wed, Jun 15, 2011 at 11:54 PM, Jason Erickson <jason@...> wrote:
                      I quite like the idea of in-band control because I like a developer to be able to look at a response and understand all of the transitions without necessarily having to go look at the documentation.  However let's not let my personal preference overly prescribe how people use HAL.

                      It seems like your (proposed?) control element could be modified slightly to allow inline templating and then those that like to give lots of in-band information would be able to do so.  So you could have something like:

                      <resource href="/" xmlns:ex="http://example.org/rels/">
                      <link rel="ex:basic" href="/bleh" />
                      <link rel="ex:search" href="/search_for;{searchTerm}" />
                      <control rel="ex:widgetate" href="/widget/{newID}" method="PUT"
                      content-type="application/x-www-form-urlencoded" template-type="application/x-www-form-urlencoded">
                      <input name="name" type="text" value="Already Existing Widget"/>
                      <select name="type">
                      <option value="ESSENTIAL" />
                      <option value="USEFUL" selected="true"/>
                      <option value="USELESS" />
                      </select>
                      </control>
                      <resource rel="ex:member" href="/foo">
                      <link rel="ex:created_by" href="/some_dude" />
                      <example>bar</example>
                      <resource rel="ex:status" href="/foo?status">
                      <status>disabled</status>
                      </resource>
                      </resource>
                      </resource>
                      Then, the in-band people like me are satisfied, but it's still generic enough to support whatever other content-types can be conceived of and of course, you can still have the @template to specify out-of-band if you prefer.  

                      Note, in the above example, if the valid choices for type of widget is dynamic, then in-band is the only practical way (that I can think of) to express that in a template.

                      Also, while forms have the advantage of being well understood, if having your stuff in-band is really the goal and you'd rather use JSON (or some other format), then inlining your template would also allow:

                      <resource href="/" xmlns:ex="http://example.org/rels/">
                      <link rel="ex:basic" href="/bleh" />
                      <link rel="ex:search" href="/search_for;{searchTerm}" />
                      <control rel="ex:widgetate" href="/widget/{newID}" method="PUT"
                      content-type="application/json" >
                      <![CDATA[
                      {
                        "name":"{{name}}",
                        "type":"{{type}}"
                      }
                      ]]>
                      </control>
                      <resource rel="ex:member" href="/foo">
                      <link rel="ex:created_by" href="/some_dude" />
                      <example>bar</example>
                      <resource rel="ex:status" href="/foo?status">
                      <status>disabled</status>
                      </resource>
                      </resource>
                      </resource>


                      On Jun 15, 2011, at 2:45 PM, Mike Kelly wrote:


                      On Wed, Jun 15, 2011 at 10:11 PM, Solomon Duskis <sduskis@...> wrote:
                      On Wed, Jun 15, 2011 at 3:51 PM, Mike Kelly <mike@...> wrote:
                      I actually thought about adding form-like/templated write to HAL. The problem is that it adds quite a lot of complexity and I'm still not convinced it's terribly useful. So instead I'm going to create a separate media type which just extends it to add this capability. Here's an example of what that could look like : https://gist.github.com/893552

                      Interesting...  but wouldn't good ol' form data work for most <control> cases?  Is there a way to KISS and have only marginal complexity addition?

                      Well that wouldn't be generic, and would significantly limit the number of existing resources on the web that the requests could be directed at.  
                       
                       
                      Also; you could actually define restbucks as an application that's "just" driven by link relations and express that with HAL. The app would lose any in-band dynamism you would expect from the use of form-like controls though.
                       
                      It would require "just" link relations and "just" minor out-of-band information (mostly methods, some message structure data as well).  Is that what you mean by losing "in-band dynamis?

                      Yes, some people consider this application design lacking. Personally, I'm quite happy to use link relations this way - hence why form-like stuff is left out of HAL and will be introduced as part of a separate type.

                      Cheers,
                      Mike

                      --
                      You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
                      To post to this group, send email to hypermedia-web@....
                      To unsubscribe from this group, send email to hypermedia-web+unsubscribe@....
                      For more options, visit this group at http://groups.google.com/group/hypermedia-web?hl=en.

                      --
                      You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
                      To post to this group, send email to hypermedia-web@....
                      To unsubscribe from this group, send email to hypermedia-web+unsubscribe@....
                      For more options, visit this group at http://groups.google.com/group/hypermedia-web?hl=en.

                    • Mike Kelly
                      As it stands, the plan is still to create a separate media type in which to add all this templated write stuff. Cheers, Mike
                      Message 10 of 14 , Jun 16, 2011
                      • 0 Attachment
                        As it stands, the plan is still to create a separate media type in which to add all this templated write stuff.

                        Cheers,
                        Mike 

                        On Thu, Jun 16, 2011 at 11:55 AM, Mike Kelly <mike@...> wrote:
                        I think what your proposing here is to bring the template/form 'in-line', rather than 'in-band'. From my pov, both template (i.e. linked or in-line) approaches bring the control in-band, as opposed to 'heavily typed links' where the control is out-of-band [1].

                        Regardless, it definitely makes a lot of sense to provide the option for the template itself to be placed in-line. Thanks for bringing that up.

                        One small gripe with your in-line example is the use of @template-type.. this should be a URI that identifies the template/form type you are using i.e. in the first example its value should be something like "http://www.w3.org/TR/html401/interact/forms"


                        Cheers,
                        Mike 


                        On Wed, Jun 15, 2011 at 11:54 PM, Jason Erickson <jason@...> wrote:
                        I quite like the idea of in-band control because I like a developer to be able to look at a response and understand all of the transitions without necessarily having to go look at the documentation.  However let's not let my personal preference overly prescribe how people use HAL.

                        It seems like your (proposed?) control element could be modified slightly to allow inline templating and then those that like to give lots of in-band information would be able to do so.  So you could have something like:

                        <resource href="/" xmlns:ex="http://example.org/rels/">
                        <link rel="ex:basic" href="/bleh" />
                        <link rel="ex:search" href="/search_for;{searchTerm}" />
                        <control rel="ex:widgetate" href="/widget/{newID}" method="PUT"
                        content-type="application/x-www-form-urlencoded" template-type="application/x-www-form-urlencoded">
                        <input name="name" type="text" value="Already Existing Widget"/>
                        <select name="type">
                        <option value="ESSENTIAL" />
                        <option value="USEFUL" selected="true"/>
                        <option value="USELESS" />
                        </select>
                        </control>
                        <resource rel="ex:member" href="/foo">
                        <link rel="ex:created_by" href="/some_dude" />
                        <example>bar</example>
                        <resource rel="ex:status" href="/foo?status">
                        <status>disabled</status>
                        </resource>
                        </resource>
                        </resource>
                        Then, the in-band people like me are satisfied, but it's still generic enough to support whatever other content-types can be conceived of and of course, you can still have the @template to specify out-of-band if you prefer.  

                        Note, in the above example, if the valid choices for type of widget is dynamic, then in-band is the only practical way (that I can think of) to express that in a template.

                        Also, while forms have the advantage of being well understood, if having your stuff in-band is really the goal and you'd rather use JSON (or some other format), then inlining your template would also allow:

                        <resource href="/" xmlns:ex="http://example.org/rels/">
                        <link rel="ex:basic" href="/bleh" />
                        <link rel="ex:search" href="/search_for;{searchTerm}" />
                        <control rel="ex:widgetate" href="/widget/{newID}" method="PUT"
                        content-type="application/json" >
                        <![CDATA[
                        {
                          "name":"{{name}}",
                          "type":"{{type}}"
                        }
                        ]]>
                        </control>
                        <resource rel="ex:member" href="/foo">
                        <link rel="ex:created_by" href="/some_dude" />
                        <example>bar</example>
                        <resource rel="ex:status" href="/foo?status">
                        <status>disabled</status>
                        </resource>
                        </resource>
                        </resource>


                        On Jun 15, 2011, at 2:45 PM, Mike Kelly wrote:


                        On Wed, Jun 15, 2011 at 10:11 PM, Solomon Duskis <sduskis@...> wrote:
                        On Wed, Jun 15, 2011 at 3:51 PM, Mike Kelly <mike@...> wrote:
                        I actually thought about adding form-like/templated write to HAL. The problem is that it adds quite a lot of complexity and I'm still not convinced it's terribly useful. So instead I'm going to create a separate media type which just extends it to add this capability. Here's an example of what that could look like : https://gist.github.com/893552

                        Interesting...  but wouldn't good ol' form data work for most <control> cases?  Is there a way to KISS and have only marginal complexity addition?

                        Well that wouldn't be generic, and would significantly limit the number of existing resources on the web that the requests could be directed at.  
                         
                         
                        Also; you could actually define restbucks as an application that's "just" driven by link relations and express that with HAL. The app would lose any in-band dynamism you would expect from the use of form-like controls though.
                         
                        It would require "just" link relations and "just" minor out-of-band information (mostly methods, some message structure data as well).  Is that what you mean by losing "in-band dynamis?

                        Yes, some people consider this application design lacking. Personally, I'm quite happy to use link relations this way - hence why form-like stuff is left out of HAL and will be introduced as part of a separate type.

                        Cheers,
                        Mike

                        --
                        You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
                        To post to this group, send email to hypermedia-web@....
                        To unsubscribe from this group, send email to hypermedia-web+unsubscribe@....
                        For more options, visit this group at http://groups.google.com/group/hypermedia-web?hl=en.

                        --
                        You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
                        To post to this group, send email to hypermedia-web@....
                        To unsubscribe from this group, send email to hypermedia-web+unsubscribe@....
                        For more options, visit this group at http://groups.google.com/group/hypermedia-web?hl=en.


                      • Jason Erickson
                        You are right, I meant in-line. And yes, the @template-type should be a URI - that makes more sense.
                        Message 11 of 14 , Jun 16, 2011
                        • 0 Attachment
                          You are right, I meant in-line.  And yes, the @template-type should be a URI - that makes more sense.

                          On Jun 16, 2011, at 3:55 AM, Mike Kelly wrote:

                          I think what your proposing here is to bring the template/form 'in-line', rather than 'in-band'. From my pov, both template (i.e. linked or in-line) approaches bring the control in-band, as opposed to 'heavily typed links' where the control is out-of-band [1].

                          Regardless, it definitely makes a lot of sense to provide the option for the template itself to be placed in-line. Thanks for bringing that up.

                          One small gripe with your in-line example is the use of @template-type.. this should be a URI that identifies the template/form type you are using i.e. in the first example its value should be something like "http://www.w3.org/TR/html401/interact/forms"


                          Cheers,
                          Mike 

                          On Wed, Jun 15, 2011 at 11:54 PM, Jason Erickson <jason@...> wrote:
                          I quite like the idea of in-band control because I like a developer to be able to look at a response and understand all of the transitions without necessarily having to go look at the documentation.  However let's not let my personal preference overly prescribe how people use HAL.

                        • Suresh Kumar
                          Hello Mike, For one of our in-house RESTFul application, we started off defining a domain specific XML vocabulary but ended with a generic XML vocubulary to
                          Message 12 of 14 , Jun 18, 2011
                          • 0 Attachment
                            Hello Mike,

                            For one of our in-house RESTFul application, we started off defining a domain specific XML vocabulary but ended with a generic XML vocubulary to describe resources which looks a little similar to what you have proposed. One of the major goal of the vocabulary definition was to have the ability to describe all resources in uniform and consistent manner. Initially we started designing the vocabulary around the semantics of each resource and found out soon that it was harder to maintain. We then decided to make a generic "resource" vocabulary i.e. the vocabulary was aimed at to be applicable to a large set of resources as possible. 

                            The design considered that anything exposed by our application is a resource which can be linked and provides links to other relevant resources so we also included hypermedia controls in the vocabulary similar to what you have done.

                            The following is how the vocabulary looks like:

                            <resource href="xsd:anyURI" rel="rels:rel"/>   

                               

                                <!-- Links to related resources -->

                                <refs>

                                    <link rel="rels:rel" href="xsd:anyURI" />

                                </refs>

                               

                                <!-- Navigational links if listing a large collection of resources -->

                                <nav>

                                    <link rel="rels:next" href="xsd:anyURI"/>

                                    <link rel="rels:previous" href="xsd:anyURI"/>

                                    <link rel="rels:first" href="xsd:anyURI"/>

                                    <link rel="rels:last" href="xsd:anyURI"/>

                                </nav>

                               

                                <!-- Include any number of resource properties here -->

                                <!-- Use XSD types -->

                                <property name="xsd:string" type="xsd:nnn"></property>

                                <property name="xsd:string" type="xsd:nnn"></property>

                               

                                <!-- Use Custom types -->

                                <property name="xsd:string" type="mytypes:YYY"></property>

                               

                                <!-- Include another resource -->

                                <property type="resource">

                                    <resource href="xsd:anyURI" rel="rels:rel">

                                        <!-- Include any number of resource properties here -->

                                        <property name="xsd:string" type="xsd:nnn"></property>

                                        <property name="xsd:string" type="xsd:nnn"></property>         

                                    </resource>

                                </property>

                               

                            </resource>


                            An example using the above vocabulary is:

                            <resource href="http://mycompany.com/books/fiction" rel="rels:fiction" >

                               

                                <property name="description" type="xsd:string"> Browse Books <property>

                               

                                <refs>

                               <link href="http://abc.com/books/fiction/popular" rel="rels:popular"/>

                                </refs>

                             

                                <property type="resource">

                                    <resource href="http://abc.com/books/HGTHG" rel="rels:book">             

                                        <refs>

                                       <link href="http://abc.com/books/HGTHG_all" rel="rels:related"/>

                                        </refs>

                                       

                                        <property name="author" type="xsd:string">Douglas Adams</property>

                                        <property name="title" type="xsd:string">Hitch Hiker's Guide to</property>              

                                        <property name="price" type="mytypes:amount">$65</property>                        

                                   

                                    </resource>

                                </property>

                               

                                <property

                          • Erik Wilde
                            [sorry Erik, just found this in the moderation queue... Mark] hello mike. ... this looks very interesting! it has many similarities to something rosa alarcon
                            Message 13 of 14 , Jun 21, 2011
                            • 0 Attachment
                              [sorry Erik, just found this in the moderation queue... Mark]

                              hello mike.

                              On 2011-06-14 9:17 , Mike Kelly wrote:
                              > I've now produced an initial draft of a spec for a minimalist, generic
                              > media type. Love to get some feedback + pointers on this

                              this looks very interesting! it has many similarities to something rosa
                              alarcon and i worked on that we called the "Resource Linking Language
                              (ReLL)", which probably had pretty much the same starting point.
                              however, one important difference may be that we see ReLL mostly as a
                              description language (even though we usually don't say that because this
                              is a seriously bad word in RESTful circles) that allows clients to
                              traverse across an interlinked set of resources, extracting links from
                              them through media-type specific selection languages (mostly XPath for
                              XML right now), and understanding those links based on link semantics
                              defined in ReLL. the main idea behind ReLL is that you can produce a
                              ReLL description of a set of interlinked resources without any need to
                              change them, so clients can start using ReLL without server/publishers
                              even knowing about it. we used that capability when we described web
                              pages via ReLL, and than had a ReLL-steered crawler harvesting RDF from
                              those pages, directed only by the declarative ReLL overlay on top of the
                              web pages.

                              we are still working on ReLL and unfortunately, there is no recent
                              publication (or let alone a specification) we could point you to, but
                              http://dret.net/netdret/publications#ala10a and
                              http://dret.net/netdret/publications#ala10c should be sufficient to
                              provide an overview of our approach and our language.

                              cheers,

                              dret.

                              --

                              erik wilde | mailto:dret@... - tel:+1-510-6432253 |
                              | UC Berkeley - School of Information (ISchool) |
                              | http://dret.net/netdret http://twitter.com/dret |
                            • adam@littlefyr.com
                              I have to wonder if this isn t simply duplicating work that already exists. Topic maps have a data model more than adequate to do this sort of thing (on
                              Message 14 of 14 , Jul 4 8:34 AM
                              • 0 Attachment
                                I have to wonder if this isn't simply duplicating work that already exists.

                                Topic maps have a data model more than adequate to do this sort of thing (on transit with a blackberry is not the place to verify that robustly) and its an international standard.

                                It is used most often in publishing and knowledge management but it is perfectly suited to a REST application.

                                The difficult bit is that it is VERY abstract (everything is either a topic, association or occurrence) which will cause trouble for some. It is also a data model (not a media type) with two (that I know of) representations (XTM and LTM).

                                I suggest that someone craft a sufficiently non-trivial problem and we all show how our solutions would apply.

                                Adam

                                Sent from my BlackBerry device on the Rogers Wireless Network


                                From: Erik Wilde <dret@...>
                                Sender: rest-discuss@yahoogroups.com
                                Date: Tue, 21 Jun 2011 12:27:59 -0700
                                To: REST-Discuss<rest-discuss@yahoogroups.com>
                                Subject: [rest-discuss] HAL and ReLL

                                 

                                [sorry Erik, just found this in the moderation queue... Mark]

                                hello mike.

                                On 2011-06-14 9:17 , Mike Kelly wrote:
                                > I've now produced an initial draft of a spec for a minimalist, generic
                                > media type. Love to get some feedback + pointers on this

                                this looks very interesting! it has many similarities to something rosa
                                alarcon and i worked on that we called the "Resource Linking Language
                                (ReLL)", which probably had pretty much the same starting point.
                                however, one important difference may be that we see ReLL mostly as a
                                description language (even though we usually don't say that because this
                                is a seriously bad word in RESTful circles) that allows clients to
                                traverse across an interlinked set of resources, extracting links from
                                them through media-type specific selection languages (mostly XPath for
                                XML right now), and understanding those links based on link semantics
                                defined in ReLL. the main idea behind ReLL is that you can produce a
                                ReLL description of a set of interlinked resources without any need to
                                change them, so clients can start using ReLL without server/publishers
                                even knowing about it. we used that capability when we described web
                                pages via ReLL, and than had a ReLL-steered crawler harvesting RDF from
                                those pages, directed only by the declarative ReLL overlay on top of the
                                web pages.

                                we are still working on ReLL and unfortunately, there is no recent
                                publication (or let alone a specification) we could point you to, but
                                http://dret.net/netdret/publications#ala10a and
                                http://dret.net/netdret/publications#ala10c should be sufficient to
                                provide an overview of our approach and our language.

                                cheers,

                                dret.

                                --

                                erik wilde | mailto:dret@... - tel:+1-510-6432253 |
                                | UC Berkeley - School of Information (ISchool) |
                                | http://dret.net/netdret http://twitter.com/dret |

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