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

Documenting RESTful Web Services

Expand Messages
  • Matt Gushee
    Hi, all-- I m wondering what people are thinking about the best ways to describe RESTful Web Services to clients and/or people, and how to access those
    Message 1 of 3 , Sep 2, 2002
    • 0 Attachment
      Hi, all--

      I'm wondering what people are thinking about the best ways to describe
      RESTful Web Services to clients and/or people, and how to access those
      descriptions. Shortly after I joined this list there was a good deal of
      discussion of Paul's WRDL effort ... and as I recall, there was some
      sense that perhaps we should be trying to improve WSDL instead of
      reinventing the wheel ... and then the whole topic seems to have been
      abandoned.

      Of course, I realize that there have been a variety of threads that
      touched on the description/documentation issue, but there has been no
      concerted effort to tackle it head-on for quite a while. I'm not sure
      whether that means everyone thinks it's too early to try to reach
      consensus, or people just aren't terribly concerned about it, or what.
      Yet it seems to me that being able to say "this is how you get
      information about resources" will help REST gain credibility (okay,
      the critics love it already, but will it play in Peoria?), while
      providing some valuable guidance for implementors.

      I'm not about to suggest that we immediately lurch into a WSDL-like
      standards-making effort. But might it not be a good idea to have a
      semi-coherent collection of best practices for service description?

      Or have I missed something?

      --
      Matt Gushee
      Englewood, Colorado, USA
      mgushee@...
      http://www.havenrock.com/
    • inthedarkplace
      Matt, I ve developed to very simple XML applications I use to describe my RESTful webservices. RWS-RMS (Resource Model Space) describes what resources a
      Message 2 of 3 , Sep 3, 2002
      • 0 Attachment
        Matt,

        I've developed to very simple XML applications I use to describe my
        RESTful webservices. RWS-RMS (Resource Model Space) describes what
        resources a webservice exposes and RWS-IL (Interface Language). You
        can have many webservices each with their own RWS-RMS document
        (explaining where their resources are located) but sharing the same
        RWS-IL document explaining what you can do to thos resources.

        I've spent the last 2 weeks tackling this problem of describing
        webservices and I don't think it's a problem that should be solved
        completely just yet. Reasons:

        1) There's still no elegant way to describe an XML document's
        structure. I consider XML-Schema unusable and there's zero tool
        support for RELAX-NG. I've been investigating schematron which looks
        somewhat simpler but convoluted.

        2) There are several issues with auto-proxy generation and REST,
        particularly: should it be done at all? I've been thinking a lot
        about it this. PaulPrescod has mentioned part of the value of REST is
        that it forces developers to acknowledge the network and deal with
        the kind-of-low-level-stuff like response codes. I think he may be
        right to an extent but I'm not sure.

        Between 1 and 2 it's hard to make much progress. For now, I'd agree
        with Roger: the best way to describe your webservice in a truly
        meaningful manner that will be accessible to the greatest number of
        people is to use HTML and document it.

        - itdp

        --- In rest-discuss@y..., Matt Gushee <mgushee@h...> wrote:
        > Hi, all--
        >
        > I'm wondering what people are thinking about the best ways to
        describe
        > RESTful Web Services to clients and/or people, and how to access
        those
        > descriptions. Shortly after I joined this list there was a good
        deal of
        > discussion of Paul's WRDL effort ... and as I recall, there was
        some
        > sense that perhaps we should be trying to improve WSDL instead of
        > reinventing the wheel ... and then the whole topic seems to have
        been
        > abandoned.
        >
        > Of course, I realize that there have been a variety of threads that
        > touched on the description/documentation issue, but there has been
        no
        > concerted effort to tackle it head-on for quite a while. I'm not
        sure
        > whether that means everyone thinks it's too early to try to reach
        > consensus, or people just aren't terribly concerned about it, or
        what.
        > Yet it seems to me that being able to say "this is how you get
        > information about resources" will help REST gain credibility (okay,
        > the critics love it already, but will it play in Peoria?), while
        > providing some valuable guidance for implementors.
        >
        > I'm not about to suggest that we immediately lurch into a WSDL-like
        > standards-making effort. But might it not be a good idea to have a
        > semi-coherent collection of best practices for service description?
        >
        > Or have I missed something?
        >
        > --
        > Matt Gushee
        > Englewood, Colorado, USA
        > mgushee@h...
        > http://www.havenrock.com/
      • Matt Gushee
        ... Interesting. How do I find out more about this? ... Zero tool support for RELAX-NG? I guess it depends on what you mean by a tool. ... I agree with the
        Message 3 of 3 , Sep 3, 2002
        • 0 Attachment
          On Tue, Sep 03, 2002 at 09:46:18AM -0000, inthedarkplace wrote:
          >
          > I've developed to very simple XML applications I use to describe my
          > RESTful webservices. RWS-RMS (Resource Model Space) describes what
          > resources a webservice exposes and RWS-IL (Interface Language). You
          > can have many webservices each with their own RWS-RMS document
          > (explaining where their resources are located) but sharing the same
          > RWS-IL document explaining what you can do to thos resources.

          Interesting. How do I find out more about this?

          > I've spent the last 2 weeks tackling this problem of describing
          > webservices and I don't think it's a problem that should be solved
          > completely just yet. Reasons:
          >
          > 1) There's still no elegant way to describe an XML document's
          > structure. I consider XML-Schema unusable and there's zero tool
          > support for RELAX-NG. I've been investigating schematron which looks
          > somewhat simpler but convoluted.

          Zero tool support for RELAX-NG? I guess it depends on what you mean by a
          tool.

          > 2) There are several issues with auto-proxy generation and REST,
          > particularly: should it be done at all? I've been thinking a lot
          > about it this. PaulPrescod has mentioned part of the value of REST is
          > that it forces developers to acknowledge the network and deal with
          > the kind-of-low-level-stuff like response codes. I think he may be
          > right to an extent but I'm not sure.
          >
          > Between 1 and 2 it's hard to make much progress. For now, I'd agree
          > with Roger: the best way to describe your webservice in a truly
          > meaningful manner that will be accessible to the greatest number of
          > people is to use HTML and document it.

          I agree with the bulk of your argument, but not entirely with the
          conclusion. Certainly, human-readable documentation is currently the
          only sound basis for client-side development--and I would go even
          farther than you, to say that there will probably *always* be a need for
          it: maybe it's just my liberal-arts background talking, but as far as
          I'm concerned, the notion of 'intelligent agents' crawling the web, and
          finding and processing the right resources without human intervention is
          science fiction (which means it has a 27.3% chance of coming true :-).

          Even setting that dubious vision aside, there are those who would argue
          that resources can/should be self-describing. To which I would answer
          that 'self-description' is always relative to some context, and the
          meanings expressed in any given information resource are more
          context-dependent than most people realize. And even though users are
          welcome to use resources as they see fit (that's the nature of the web,
          after all), many people will find a prose description of the author's
          ideas about the data to be valuable.

          So, yes, we need to document our services in human-readable form, now
          and in the foreseeable future. But I think 'use HTML and document it'
          glosses over some important questions that are, if not resolvable, at
          least discussable here and now. One in particular that concerns me--
          and I think would be of value to many prospective RESTful developers
          --is how to access the documentation for a web service. Since REST is
          not a programming language, maybe it's inappropriate to compare it to
          one, but I can't help thinking about the documentation conventions used
          in, say, Java and Python. Developers know how to extract documentation
          from any library they want to use, and even if the developer of that
          library has completely neglected to describe anything, they can still
          obtain the bare essentials of the API.

          So suppose we had conventions for structuring the documentation for web
          resources, and a conventional way of querying resources to obtain their
          documentation? Wouldn't that be a good thing?

          [ I've actually made a stab in the direction of developing such
          conventions: in a demo I put together for a presentation back
          in February, I wrote resource descriptions using Dublin Core
          with embedded XHTML elements (e.g. <xhtml:p> inside
          <dc:Description>), and to obtain the description you would use
          the resource URI with a trailing '?' ... yes, it was a nasty hack.
          Oh well ... ]

          What are the obstacles to developing such conventions?

          --
          Matt Gushee
          Englewood, Colorado, USA
          mgushee@...
          http://www.havenrock.com/
        Your message has been successfully submitted and would be delivered to recipients shortly.