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

REST API For Documentation?

Expand Messages
  • Jim Purbrick
    While thinking about documentation for the API we re working on one of our team suggested building a REST API to document the REST API. Resources in the
    Message 1 of 10 , Sep 20, 2011
      While thinking about documentation for the API we're working on one of
      our team suggested building a REST API to document the REST API.
      Resources in the documentation API would correspond to media types and
      contain data on the methods and properties available in those media
      types.

      Has anyone seen this done before? How did it work out? Are there a set
      of media types for describing RESTful media types that we can reuse?
      The goal here would be to reuse the API infrastructure to serve the
      documentation and to allow client side formatting of the documentation
      (rather than building heavyweight WS* formats describing formats for
      validation etc.).

      Cheers,

      Jim
    • Jan Algermissen
      ... Are you asking about service documentation [1] or media type documentation ? Jan [1] Which makes your service unRESTful immediately. E.g see
      Message 2 of 10 , Sep 20, 2011
        On Sep 20, 2011, at 3:22 PM, Jim Purbrick wrote:

        > While thinking about documentation for the API we're working on

        Are you asking about 'service documentation'[1] or 'media type documentation'?


        Jan

        [1] Which makes your service unRESTful immediately.

        E.g see <http://stackoverflow.com/questions/7355084/publishing-documenting-spring-rest-api/7482941#7482941>





        > one of
        > our team suggested building a REST API to document the REST API.
        > Resources in the documentation API would correspond to media types and
        > contain data on the methods and properties available in those media
        > types.
        >
        > Has anyone seen this done before? How did it work out? Are there a set
        > of media types for describing RESTful media types that we can reuse?
        > The goal here would be to reuse the API infrastructure to serve the
        > documentation and to allow client side formatting of the documentation
        > (rather than building heavyweight WS* formats describing formats for
        > validation etc.).
        >
        > Cheers,
        >
        > Jim
        >
      • Jan Algermissen
        ... Great [:-)]. I am afraid there is necessarily much prose involved. Though some aspect of a media type is that it defines a superset of structural
        Message 3 of 10 , Sep 20, 2011
          On Sep 20, 2011, at 3:47 PM, Jim Purbrick wrote:

          >> On Sep 20, 2011, at 3:22 PM, Jim Purbrick wrote:
          >>
          >>> While thinking about documentation for the API we're working on
          >>
          >> Are you asking about 'service documentation'[1] or 'media type documentation'?
          >
          > Media type documentation.

          Great [:-)]. I am afraid there is necessarily much prose involved. Though some aspect of a media type is that it defines a superset of structural abstractions of server side state ( e.g. Feed entries have a title, feeds have entries,..) and a set of hypermedia semantics ( 'entry2 is edit-resource of entry1). These could be formalized - but I doubt that we are anywhere close to that , yet.

          @Mike? I recall you did some work on this, lately?

          Jan


          > The documentation API would just be a
          > collection of descriptions of media types.
          >
          > Cheers,
          >
          > Jim
        • Subbu Allamaraju
          ... Very pedantic, and not a helpful guidance. Subbu
          Message 4 of 10 , Sep 20, 2011
            On Sep 20, 2011, at 6:41 AM, Jan Algermissen wrote:

            > [1] Which makes your service unRESTful immediately.

            Very pedantic, and not a helpful guidance.

            Subbu
          • Jan Algermissen
            ... pedantic has such a negative connotation, doesn t it? not helpful does, too. .... which, one might say is in turn not very helpful :-) (And: what makes
            Message 5 of 10 , Sep 20, 2011
              On Sep 20, 2011, at 7:58 PM, Subbu Allamaraju wrote:

              >
              > On Sep 20, 2011, at 6:41 AM, Jan Algermissen wrote:
              >
              >> [1] Which makes your service unRESTful immediately.
              >
              > Very pedantic, and not a helpful guidance.

              'pedantic' has such a negative connotation, doesn't it? 'not helpful' does, too. .... which, one might say is in turn not very helpful :-)
              (And: what makes a guidance helpful, BTW?)



              As always: IMHO, sticking to the principles laid out by the thesis helps learning. Doing away with a principle just because it *appears* to be impractical can keep you from learning what you need to learn to see the usefulness of the principle in the first place.

              I see no advantage whatsoever in using API descriptions instead of media type definitions. The amount of work is the same - the difference is who owns the contract. The service owner or some global (including my-enterprise-global) institution.

              In addition, being not RESTful might be perfectly fine for your scenario - but it still helps to understand what that means and what the tradeoffs are.

              Jan



              >
              > Subbu
              >
              >
              > ------------------------------------
              >
              > Yahoo! Groups Links
              >
              >
              >
            • Subbu Allamaraju
              Understood, but I would still classify this as pedantic guidance not based on systemic qualities. Please see [1]. Subbu [1]
              Message 6 of 10 , Sep 20, 2011
                Understood, but I would still classify this as pedantic guidance not based on systemic qualities. Please see [1].

                Subbu

                [1] http://www.subbu.org/blog/2011/08/measuring-rest-2

                On Sep 20, 2011, at 11:19 AM, Jan Algermissen wrote:

                >
                > On Sep 20, 2011, at 7:58 PM, Subbu Allamaraju wrote:
                >
                >>
                >> On Sep 20, 2011, at 6:41 AM, Jan Algermissen wrote:
                >>
                >>> [1] Which makes your service unRESTful immediately.
                >>
                >> Very pedantic, and not a helpful guidance.
                >
                > 'pedantic' has such a negative connotation, doesn't it? 'not helpful' does, too. .... which, one might say is in turn not very helpful :-)
                > (And: what makes a guidance helpful, BTW?)
                >
                >
                >
                > As always: IMHO, sticking to the principles laid out by the thesis helps learning. Doing away with a principle just because it *appears* to be impractical can keep you from learning what you need to learn to see the usefulness of the principle in the first place.
                >
                > I see no advantage whatsoever in using API descriptions instead of media type definitions. The amount of work is the same - the difference is who owns the contract. The service owner or some global (including my-enterprise-global) institution.
                >
                > In addition, being not RESTful might be perfectly fine for your scenario - but it still helps to understand what that means and what the tradeoffs are.
                >
                > Jan
                >
                >
                >
                >>
                >> Subbu
                >>
                >>
                >> ------------------------------------
                >>
                >> Yahoo! Groups Links
                >>
                >>
                >>
                >
              • Jan Algermissen
                ... Ok - so you are saying there is no value in insisting in doing REST when you do not yet understand how to judge whether you actually need to be RESTful?
                Message 7 of 10 , Sep 20, 2011
                  On Sep 20, 2011, at 8:30 PM, Subbu Allamaraju wrote:

                  > Understood, but I would still classify this as pedantic guidance not based on systemic qualities. Please see [1].

                  Ok - so you are saying there is 'no' value in insisting in doing REST when you do not yet understand how to judge whether you actually need to be RESTful?

                  I'd agree with that - to me, the true value of Roy's thesis is that it guides you how to make such decisions in the first place[1]


                  I think the key issue of doing REST behind the firewall is whether the evolvability you gain with REST (say over my HTTP Type I) will pay off or not. And how it will pay off exactly.

                  FWIW, inside enterprise boundaries, any advantages will be seen not so much in long term (decades) evolvability but much more in more flexible deployment scenarios in the context of constant, short notice, changes or a more grassroots and experimental style of exploring new features.

                  Jan

                  [1] And there is still surprisingly few material exploring that aspect of the software architecture profession



                  >
                  > Subbu
                  >
                  > [1] http://www.subbu.org/blog/2011/08/measuring-rest-2
                  >
                  > On Sep 20, 2011, at 11:19 AM, Jan Algermissen wrote:
                  >
                  > >
                  > > On Sep 20, 2011, at 7:58 PM, Subbu Allamaraju wrote:
                  > >
                  > >>
                  > >> On Sep 20, 2011, at 6:41 AM, Jan Algermissen wrote:
                  > >>
                  > >>> [1] Which makes your service unRESTful immediately.
                  > >>
                  > >> Very pedantic, and not a helpful guidance.
                  > >
                  > > 'pedantic' has such a negative connotation, doesn't it? 'not helpful' does, too. .... which, one might say is in turn not very helpful :-)
                  > > (And: what makes a guidance helpful, BTW?)
                  > >
                  > >
                  > >
                  > > As always: IMHO, sticking to the principles laid out by the thesis helps learning. Doing away with a principle just because it *appears* to be impractical can keep you from learning what you need to learn to see the usefulness of the principle in the first place.
                  > >
                  > > I see no advantage whatsoever in using API descriptions instead of media type definitions. The amount of work is the same - the difference is who owns the contract. The service owner or some global (including my-enterprise-global) institution.
                  > >
                  > > In addition, being not RESTful might be perfectly fine for your scenario - but it still helps to understand what that means and what the tradeoffs are.
                  > >
                  > > Jan
                  > >
                  > >
                  > >
                  > >>
                  > >> Subbu
                  > >>
                  > >>
                  > >> ------------------------------------
                  > >>
                  > >> Yahoo! Groups Links
                  > >>
                  > >>
                  > >>
                  > >
                  >
                  >
                • Subbu Allamaraju
                  Nope - we can t arbitrarily use qualities like evolvability without applying them to a context (such as the conditions in which clients are servers are
                  Message 8 of 10 , Sep 20, 2011
                    Nope - we can't arbitrarily use qualities like "evolvability" without applying them to a context (such as the conditions in which clients are servers are working). The guidance becomes pedantic when you don't contextualize the qualities - consequently you won't be able to measure the outcome. For instance "evolvability" could mean "writing a new client app in a week" - there may be several ways to get to that measurement. The task is to pick one.

                    The key thing to learn is not "how to do 100% REST" but how to build apps that meet certain **measurable** qualities. Roy's work in Chapter 2 gives a good starting point, but the list of qualities that apply to a given app may be different.

                    Subbu

                    On Sep 20, 2011, at 12:01 PM, Jan Algermissen wrote:

                    >
                    > On Sep 20, 2011, at 8:30 PM, Subbu Allamaraju wrote:
                    >
                    >> Understood, but I would still classify this as pedantic guidance not based on systemic qualities. Please see [1].
                    >
                    > Ok - so you are saying there is 'no' value in insisting in doing REST when you do not yet understand how to judge whether you actually need to be RESTful?
                    >
                    > I'd agree with that - to me, the true value of Roy's thesis is that it guides you how to make such decisions in the first place[1]
                    >
                    >
                    > I think the key issue of doing REST behind the firewall is whether the evolvability you gain with REST (say over my HTTP Type I) will pay off or not. And how it will pay off exactly.
                    >
                    > FWIW, inside enterprise boundaries, any advantages will be seen not so much in long term (decades) evolvability but much more in more flexible deployment scenarios in the context of constant, short notice, changes or a more grassroots and experimental style of exploring new features.
                    >
                    > Jan
                    >
                    > [1] And there is still surprisingly few material exploring that aspect of the software architecture profession
                    >
                    >
                    >
                    >>
                    >> Subbu
                    >>
                    >> [1] http://www.subbu.org/blog/2011/08/measuring-rest-2
                    >>
                    >> On Sep 20, 2011, at 11:19 AM, Jan Algermissen wrote:
                    >>
                    >>>
                    >>> On Sep 20, 2011, at 7:58 PM, Subbu Allamaraju wrote:
                    >>>
                    >>>>
                    >>>> On Sep 20, 2011, at 6:41 AM, Jan Algermissen wrote:
                    >>>>
                    >>>>> [1] Which makes your service unRESTful immediately.
                    >>>>
                    >>>> Very pedantic, and not a helpful guidance.
                    >>>
                    >>> 'pedantic' has such a negative connotation, doesn't it? 'not helpful' does, too. .... which, one might say is in turn not very helpful :-)
                    >>> (And: what makes a guidance helpful, BTW?)
                    >>>
                    >>>
                    >>>
                    >>> As always: IMHO, sticking to the principles laid out by the thesis helps learning. Doing away with a principle just because it *appears* to be impractical can keep you from learning what you need to learn to see the usefulness of the principle in the first place.
                    >>>
                    >>> I see no advantage whatsoever in using API descriptions instead of media type definitions. The amount of work is the same - the difference is who owns the contract. The service owner or some global (including my-enterprise-global) institution.
                    >>>
                    >>> In addition, being not RESTful might be perfectly fine for your scenario - but it still helps to understand what that means and what the tradeoffs are.
                    >>>
                    >>> Jan
                    >>>
                    >>>
                    >>>
                    >>>>
                    >>>> Subbu
                    >>>>
                    >>>>
                    >>>> ------------------------------------
                    >>>>
                    >>>> Yahoo! Groups Links
                    >>>>
                    >>>>
                    >>>>
                    >>>
                    >>
                    >>
                    >
                  • Jan Algermissen
                    ... Personally, the key thing for me has always been how to do 100% REST behind the firewall and what are the implications of doing that. How does my mental
                    Message 9 of 10 , Sep 20, 2011
                      On Sep 20, 2011, at 9:16 PM, Subbu Allamaraju wrote:

                      > The key thing to learn is not "how to do 100% REST" but how to build apps that meet certain **measurable** qualities.

                      Personally, the key thing for me has always been "how to do 100% REST behind the firewall" and what are the implications of doing that. How does my mental model of the systems we are building, extending and maintaining(!) change if I leverage 100% REST[1]. And in the end: does what I learned apply in a practical, beneficial way.

                      IOW, does my profession benefit from viewing enterprise IT as having the same desired system properties as the Web does. And yes, I found that it mostly does[2] and I found that the profession benefits. Hence, my quest is for 100% REST.

                      Jan

                      [1] As opposed to relaxing the constraints because I cannot fit them to my *existing* mental model.
                      [2] And where it does not, it is well worth considering rolling your own RPC instead of applying HTTP unRESTfully for the sake of applying HTTP.
                    • Subbu Allamaraju
                      ... Sure. If 100% REST is the quality you re after, please pursue - no one can object to that. Subbu
                      Message 10 of 10 , Sep 20, 2011
                        On Sep 20, 2011, at 12:36 PM, Jan Algermissen wrote:

                        > Hence, my quest is for 100% REST.

                        Sure. If "100% REST" is the quality you're after, please pursue - no one can object to that.

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