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

Re: [rest-discuss] On (API design)

Expand Messages
  • mike amundsen
    Jonas: While there is nothing wrong w/ inventing your own XML vocab (and the validators to support it), I think there is not much to gain in doing so. Using
    Message 1 of 10 , Oct 7, 2008
      Jonas:

      While there is nothing wrong w/ inventing your own XML vocab (and the
      validators to support it), I think there is not much to gain in doing
      so. Using common idioms can make your documents more accessible to
      others who want to use them, write clients against them, etc. The
      <link> idiom is common enough that there will be a good deal of
      existing code to handle them. Creating your own way to share links in
      an XML document could make that existing code worthless.

      And I don't see much downside to using the existing <link> idiom.
      Sure, there are a few more bytes in the documents, but that seems like
      a small price to pay for using a common pattern most folks already
      understand.

      mca
      http://amundsen.com/blog/




      On Tue, Oct 7, 2008 at 18:57, Jonas Galvez <jonas@...> wrote:
      > Subbu Allamaraju wrote:
      >> What is so complex about using the first choice below?
      >
      > I believe <link> is too generic/extensible, designed so that you can
      > fully describe a link only with attributes instead of having to define
      > new XML constructs.
      >
      > Since I'm designing my own vocabulary that has a very specific
      > purpose, I think it makes sense to have a convention of carrying API
      > links as attributes within the elements representing the resources
      > they point to. A hopefully clearer example:
      >
      > <my-resource ref="uri:my-resource..." />
      >
      > vs
      >
      > <my-resource><link href="uri:my-resource" /></my-resource>
      >
      > Any reasonably good reason not to do this?
      >
      > --
      > Jonas Galvez
      > Software Engineer
      > Côdeazur Brasil
      >
      > http://jonasgalvez.com.br
      > http://codeazur.com.br
      >
      > ------------------------------------
      >
      > Yahoo! Groups Links
      >
      >
      >
      >
    • Jonas Galvez
      ... Well, I m sure there are lots of HTML and Atom libraries that handle automatically but unless my API s XML vocab is a direct extension of either
      Message 2 of 10 , Oct 7, 2008
        mike amundsen wrote:
        > Using common idioms can make your documents more
        > accessible to others who want to use them, write clients
        > against them, etc. The <link> idiom is common enough
        > that there will be a good deal of existing code to handle
        > them. Creating your own way to share links in an XML
        > document could make that existing code worthless.

        Well, I'm sure there are lots of HTML and Atom libraries that handle
        <link> automatically but unless my API's XML vocab is a direct
        extension of either HTML or Atom, implementors are going to be
        required to write new XML parsing code (as is the case with most
        RESTful XML representations) and in this particular scenario, I'm not
        sure <link> parsing would be individually available for plugging in,
        or that it could have any real beneits. I tend to believe avoiding
        <link> and other compatibility constructs could actually simplify API
        client implementation.

        --Jonas Galvez
      • Subbu Allamaraju
        ... In certain cases, your proposal can simplify client implementations. Instead of getting a link child and then getting its href attribute, the client
        Message 3 of 10 , Oct 7, 2008
          On Oct 7, 2008, at 5:11 PM, Jonas Galvez wrote:

          > r that it could have any real beneits. I tend to believe avoiding
          > <link> and other compatibility constructs could actually simplify API
          > client implementation.


          In certain cases, your proposal can simplify client implementations.
          Instead of getting a "link" child and then getting its "href"
          attribute, the client could directly get the "ref" attribute. However,
          your use cases may change in future and you may need to reinvent some
          of the things that the link element already supports, leading to
          future compat issues. It is worth considering before settling on the
          "ref" approach!

          Subbu
          ---
          http://subbu.org
        • Stefan Tilkov
          Hi Jonas, I prefer the link element specifically because it s more generic. E.g. in your example …
          Message 4 of 10 , Oct 8, 2008
            Hi Jonas,

            I prefer the link element specifically because it's more generic. E.g.
            in your example …

            <link rel="orders" type="text/xml" href="/api/client/123/orders.xml" />

            … any piece of client software that understands a link element could
            visualize it, e.g. presenting the "rel" and "type" to the end user.
            Clients that understand links and text/xml (shudder, application/xml)
            could make a little more sense of it. Finally, clients understanding
            an "orders" relationship could handle _any_ kind of document that
            contains links to orders.

            In other words, I believe the usual case for a generic approach can be
            made here, especially since the disadvantage is really just a matter
            of syntactical details.

            Stefan
            --
            Stefan Tilkov, http://www.innoq.com/blog/st/


            On 08.10.2008, at 00:57, Jonas Galvez wrote:

            > Subbu Allamaraju wrote:
            > > What is so complex about using the first choice below?
            >
            > I believe <link> is too generic/extensible, designed so that you can
            > fully describe a link only with attributes instead of having to define
            > new XML constructs.
            >
            > Since I'm designing my own vocabulary that has a very specific
            > purpose, I think it makes sense to have a convention of carrying API
            > links as attributes within the elements representing the resources
            > they point to. A hopefully clearer example:
            >
            > <my-resource ref="uri:my-resource..." />
            >
            > vs
            >
            > <my-resource><link href="uri:my-resource" /></my-resource>
            >
            > Any reasonably good reason not to do this?
            >
            > --
            > Jonas Galvez
            > Software Engineer
            > Côdeazur Brasil
            >
            > http://jonasgalvez.com.br
            > http://codeazur.com.br
            >
            >
          • Subbu Allamaraju
            ... application/vnd.myorg.orders+xml ? Although such a media type is proprietary, it can be used to describe representations more formally instead of
            Message 5 of 10 , Oct 8, 2008
              > Clients that understand links and text/xml (shudder, application/xml)
              > could make a little more sense of it. Finally, clients understanding

              "application/vnd.myorg.orders+xml"?

              Although such a media type is proprietary, it can be used to describe
              representations more formally instead of overloading application/xml.

              The point that clients can recognize the link element (from the Atom
              namespace or may be even XHTML) is a bit theoretical at this time, but
              hopefully that will change in time.

              Subbu
              ---
              http://subbu.org
            • Stefan Tilkov
              ... I agree and like this much better than application/xml. Still, text/ xml is worst: http://www.w3.org/TR/2004/REC-webarch-20041215/#xml-media-types Stefan
              Message 6 of 10 , Oct 8, 2008
                On 08.10.2008, at 19:01, Subbu Allamaraju wrote:

                "application/ vnd.myorg. orders+xml" ?

                Although such a media type is proprietary, it can be used to describe 
                representations more formally instead of overloading application/ xml.

                I agree and like this much better than application/xml. Still, text/xml is worst:

                Stefan
              • Aristotle Pagaltzis
                ... That doesn’t seem like a concern to me. The basic link element pattern is trivial to handle. The complexity in handling links is in dealing with the
                Message 7 of 10 , Oct 9, 2008
                  * mike amundsen <mamund@...> [2008-10-08 01:15]:
                  > The <link> idiom is common enough that there will be a good
                  > deal of existing code to handle them. Creating your own way to
                  > share links in an XML document could make that existing code
                  > worthless.

                  That doesn’t seem like a concern to me. The basic link element
                  pattern is trivial to handle. The complexity in handling links is
                  in dealing with the constraints imposed by the container format,
                  eg. in Atom, there are specific demands on what links an Entry
                  must and must not have. That logic is going to need writing from
                  scratch for every format anyway.

                  If you’re designing a vocabulary from scratch I don’t see an
                  extremely compelling reason to go with the link element pattern
                  or break it.

                  However, note that I am arguing only about the case where you
                  *have* decided to design a new vocabulary. But that is not a step
                  to be take lightly. I would be very reluctant to do that. Even if
                  sticking with an existing standard format causes inconvenience,
                  as long as you don’t need to actively work against the format to
                  make it work, you stand to benefit greatly – through code reuse,
                  f.ex., bringing us full circle.

                  Regards,
                  --
                  Aristotle Pagaltzis // <http://plasmasturm.org/>
                Your message has been successfully submitted and would be delivered to recipients shortly.