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

notes on my experience creating a RESTful API

Expand Messages
  • Lucas Gonze
    Leigh Dodds surveyed web services APIs for XTech 2005: http://idealliance.org/proceedings/xtech05/papers/02-07-04/ I wrote a detailed response based on my
    Message 1 of 2 , Sep 2, 2005
    • 0 Attachment
      Leigh Dodds surveyed web services APIs for XTech 2005:
      http://idealliance.org/proceedings/xtech05/papers/02-07-04/

      I wrote a detailed response based on my experience creating the Webjay API:
      http://gonze.com/weblog/story/8-30-5

      One point I didn't make in my response is how embryonic RESTful web
      services are. The ideas which are common currency here have not been
      accepted by implementors. I know this because implementing them
      frequently led me to bits of technology that were blatantly broken from
      a RESTful perspective, yet the bugs were not known.

      For example, PUT handling in PHP is treated as a synonym for file
      uploading. The RESTful idea that PUT is only different from POST in
      terms of what it implies about state just didn't exist once I wandered
      from these environs over to #php.

      Similarly, using a broad range of response status codes meant that many
      user agents overwrote my error messages, so that I couldn't have an
      interface which was both user friendly and RESTful. I'm not just
      talking about browsers, either -- lwp-request makes the same mistake.

      Another problem was that there was no prior art to glean design patterns
      from. For example, there was no programmer-level documentation on the
      'hypermedia as engine of application state' constraint until Joe
      Gregorio's "Contructing or Traversing URIs?"[1] column on xml.com. That
      was a great start, but it's only a start.

      I hope these comments won't be interpreted as a bitter rant. These are
      just my notes from the field.

      - Lucas

      [1] http://www.xml.com/pub/a/2005/04/06/restful.html.
    • Jan Algermissen
      Lukas ... Yes, that is IMHO one of the biggest problems you face once you actually start to implement a system. I am having similar problems right now,
      Message 2 of 2 , Sep 3, 2005
      • 0 Attachment
        Lukas

        On Sep 3, 2005, at 12:06 AM, Lucas Gonze wrote:
        >

        > Another problem was that there was no prior art to glean design
        > patterns
        > from.

        Yes, that is IMHO one of the biggest problems you face once you
        actually start to implement a system. I am having similar problems
        right now, especially with making principled (as opposed to
        arbitrary) decisions when there are several choices to implement a
        certain functionality.

        What I would like to work an (and hopefully will) is a methodology
        for developing RESTful networked systems, including design principles
        (beyond RESTs architectural constraints). Ideally this would also
        include the issue of domain driven design, where the domain model
        should not only be used to derive MIME type or RDF namespace
        semantics but also the actual deployment of components [obviously not
        cooked yet, but that's where I would like to go].


        > For example, there was no programmer-level documentation on the
        > 'hypermedia as engine of application state' constraint until Joe
        > Gregorio's "Contructing or Traversing URIs?"[1] column on xml.com.
        > That
        > was a great start, but it's only a start.

        I think (one of) the major design principle is the goal to minimize
        the impact that domain model changes have on the components (it is an
        advantage if you can deploy them once an then more or less 'forget
        about them' since you know that

        - they are immune to backward compatible changes to the
        message semantics since they will ignore whatever they do
        not understand (partial understanding)

        - they do not make (heavy) use of hardwired URIs but instead
        discover them from the hypertext they process

        - can be functionally extended by sending them code (assuming
        you had built in things similar to JavaScript engines[1] into your
        clients before you deployed them; that way using the browser
        style for non-human controlled client components)

        [1] One thing I have been thinking about is an engine that would
        provide to the client the capability to transform RDF graphs it
        receives from newer namespace versions to the one it understands,
        given the server would send the code to do the transformation.

        >
        > I hope these comments won't be interpreted as a bitter rant. These
        > are
        > just my notes from the field.
        >

        Jan





        > - Lucas
        >
        > [1] http://www.xml.com/pub/a/2005/04/06/restful.html.
        >
        >
        >
        > ------------------------ Yahoo! Groups Sponsor --------------------
        > ~-->
        > Most low income households are not online. Help bridge the digital
        > divide today!
        > http://us.click.yahoo.com/cd_AJB/QnQLAA/TtwFAA/W6uqlB/TM
        > --------------------------------------------------------------------
        > ~->
        >
        >
        > Yahoo! Groups Links
        >
        >
        >
        >
        >
        >
        >
        >

        ________________________________________________________________________
        _______________
        Jan Algermissen, Consultant & Programmer
        http://jalgermissen.com
        Tugboat Consulting, 'Applying Web technology to enterprise IT'
        http://www.tugboat.de
      Your message has been successfully submitted and would be delivered to recipients shortly.