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

service "definition" techniques

Expand Messages
  • Carlos Eberhardt
    Hope this isn t off-topic: Is anyone using something like WADL for service definition documentation? We re (hopefully) going to have a collection of many
    Message 1 of 4 , Nov 30, 2011
      Hope this isn't off-topic:

      Is anyone using something like WADL for service definition documentation? We're (hopefully) going to have a collection of many services in multiple domains and we'll be expected to have a standard 'template' for defining/documenting a service. I'm curious if anyone in an "enterprise" situation has run into that and has any advice.

      Thanks!
      Carlos
    • Erik Wilde
      hello carlos. ... definitely not off-topic! this is a problem that a lot of people are struggling with (including us right now). at times, there is some
      Message 2 of 4 , Dec 1, 2011
        hello carlos.

        On 2011-11-30 21:08 , Carlos Eberhardt wrote:
        > Is anyone using something like WADL for service definition documentation? We're (hopefully) going to have a collection of many services in multiple domains and we'll be expected to have a standard 'template' for defining/documenting a service. I'm curious if anyone in an "enterprise" situation has run into that and has any advice.

        definitely not off-topic! this is a problem that a lot of people are
        struggling with (including us right now). at times, there is some
        general pushback to "describe" things because that might encourage
        developers to hardcode things, especially things such as URI patterns
        that they shouldn't hardcode. so "descriptions" putting URI patterns on
        top always look a little unfortunate, in the end these things probably
        have been designed for generating the server side, and not so much for
        guiding client-side developers. but in the end, if you have services,
        you want internal/external people to find them, in particular if you're
        serious about SOA and have a lot of them [1].

        there have been individual efforts to come up with a language, off the
        top of my head in addition to WADL i can list our own approach ReLL [2],
        RESTdesc [3], and SA-REST [4]. they all take a little different
        approaches and all of them have been discussed controversially. in the
        end, the main question is what you need the registry for, and what
        things you cannot so by runtime discovery. we're currently struggling
        with that, too, and i am pretty confident that we want to have some
        developer resources made accessible somewhere, such as
        tools/examples/contacts/schemas. in the end, my guess is it comes down
        to documenting representations and link relations, and this can be done
        by namespacing all these things and then using a mechanism for
        describing namespaces [5]. i think there still is room in this space for
        something to become established and easily usable so that it is useful
        across SOA domains, but as long as things are (services to their
        descriptions) linked, it's nicely RESTful even if everybody does what
        fits their needs best.

        cheers,

        dret.

        [1] http://news.ycombinator.com/item?id=3101876
        [2] http://dret.net/netdret/publications#ala10a
        [3] http://restdesc.org/
        [4] http://www.w3.org/Submission/SA-REST/
        [5] http://dret.net/netdret/publications#wil06h

        --
        erik wilde | mailto:dret@... - tel:+1-510-2061079 |
        | UC Berkeley - School of Information (ISchool) |
        | http://dret.net/netdret http://twitter.com/dret |
      • mike amundsen
        My approach to this problem (documenting Web services) is to document the Media Type that expresses the domain semantics for that service. This can be done for
        Message 3 of 4 , Dec 1, 2011
          My approach to this problem (documenting Web services) is to document the Media Type that expresses the domain semantics for that service. This can be done for custom-designed media types[1] designed for a single application domain and for existing (domain-agnostic) media types that support adding semantic meaning using "decorators" (@id, @name, @class, @rel)[2].

          The advantage of this approach (for the work I do) is that both servers and clients can use he same document; even work on development efforts independently, asynchronously. This works no matter the OS/Platform/Framework, etc. This approach also supports extending the implementation to support changes in the domain model w/ relatively little additional effort since adding new features is often done by adding new representations of data in the existing media type (i.e. no changes in the media type). And when changes in the media type are required, it can almost always be done w/o breaking any existing implementations (client or server).

          The downside of this approach is that both client and server need to understand enough of the application protocol (HTTP) to be able to implement successful components based on media type documentation. This kind of work is not "automatically" supported in any framework I know of today. That means some of the early work on a project takes more effort than just pointing an editor at a known URI and waiting for that editor to generate connector code for a set of exposed URIs w/ arguments.

          I cover the details of this approach in a recently released book[3].


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




          On Thu, Dec 1, 2011 at 11:26, Erik Wilde <dret@...> wrote:
          hello carlos.

          On 2011-11-30 21:08 , Carlos Eberhardt wrote:
          > Is anyone using something like WADL for service definition documentation?  We're (hopefully) going to have a collection of many services in multiple domains and we'll be expected to have a standard 'template' for defining/documenting a service. I'm curious if anyone in an "enterprise" situation has run into that and has any advice.

          definitely not off-topic! this is a problem that a lot of people are
          struggling with (including us right now). at times, there is some
          general pushback to "describe" things because that might encourage
          developers to hardcode things, especially things such as URI patterns
          that they shouldn't hardcode. so "descriptions" putting URI patterns on
          top always look a little unfortunate, in the end these things probably
          have been designed for generating the server side, and not so much for
          guiding client-side developers. but in the end, if you have services,
          you want internal/external people to find them, in particular if you're
          serious about SOA and have a lot of them [1].

          there have been individual efforts to come up with a language, off the
          top of my head in addition to WADL i can list our own approach ReLL [2],
          RESTdesc [3], and SA-REST [4]. they all take a little different
          approaches and all of them have been discussed controversially. in the
          end, the main question is what you need the registry for, and what
          things you cannot so by runtime discovery. we're currently struggling
          with that, too, and i am pretty confident that we want to have some
          developer resources made accessible somewhere, such as
          tools/examples/contacts/schemas. in the end, my guess is it comes down
          to documenting representations and link relations, and this can be done
          by namespacing all these things and then using a mechanism for
          describing namespaces [5]. i think there still is room in this space for
          something to become established and easily usable so that it is useful
          across SOA domains, but as long as things are (services to their
          descriptions) linked, it's nicely RESTful even if everybody does what
          fits their needs best.

          cheers,

          dret.

          [1] http://news.ycombinator.com/item?id=3101876
          [2] http://dret.net/netdret/publications#ala10a
          [3] http://restdesc.org/
          [4] http://www.w3.org/Submission/SA-REST/
          [5] http://dret.net/netdret/publications#wil06h

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


          ------------------------------------

          Yahoo! Groups Links

          <*> To visit your group on the web, go to:
             http://groups.yahoo.com/group/rest-discuss/

          <*> Your email settings:
             Individual Email | Traditional

          <*> To change settings online go to:
             http://groups.yahoo.com/group/rest-discuss/join
             (Yahoo! ID required)

          <*> To change settings via email:
             rest-discuss-digest@yahoogroups.com
             rest-discuss-fullfeatured@yahoogroups.com

          <*> To unsubscribe from this group, send an email to:
             rest-discuss-unsubscribe@yahoogroups.com

          <*> Your use of Yahoo! Groups is subject to:
             http://docs.yahoo.com/info/terms/


        • Philippe Mougin
          ... Hi Carlos, If your intent is to document REST services for people that might develop clients of those services, WADL isn t an option as it would lead to
          Message 4 of 4 , Dec 1, 2011
            --- In rest-discuss@yahoogroups.com, "Carlos Eberhardt" <carlos.eberhardt@...> wrote:
            >
            > Hope this isn't off-topic:
            >
            > Is anyone using something like WADL for service definition documentation? We're (hopefully) going to have a collection of many services in multiple domains and we'll be expected to have a standard 'template' for defining/documenting a service. I'm curious if anyone in an "enterprise" situation has run into that and has any advice.
            >

            Hi Carlos,
            If your intent is to document REST services for people that might develop clients of those services, WADL isn't an option as it would lead to unrestful coupling. One reason is that WADL specifies the URIs (or URI templates) for your resources. While communicating such information between services and clients dynamically at run-time is fine, communicating it at design time will lead clients to hardcode it, which will make them break when it changes. This is probably the biggest unrestful documentation pattern I see around these days for Web API that are supposedly RESTful.

            When documenting my own REST services I've found a lot of interesting inspiration in the documentation for the SUN Cloud API at http://kenai.com/projects/suncloudapis/pages/Home (still, this doc isn't perfect as it over-specifies a few things).

            There is also this quote from Roy Fielding that is useful when planning for documentation:
            "A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types)". (cf http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven).

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