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

summary of versioning issues

Expand Messages
  • Lucas Gonze
    I follow discussions here enough to know that versioning in RESTful APIs has been much discussed, but not enough to understand all the threads. Is there a
    Message 1 of 8 , Sep 29, 2010
    • 0 Attachment
      I follow discussions here enough to know that versioning in RESTful
      APIs has been much discussed, but not enough to understand all the
      threads.

      Is there a write-up summarizing the issues?
    • Eric J. Bowman
      ... Not that I know of. I won t summarize the issues, but I can list the positions: 1) You don t need versioning in REST, just like there was no versioning
      Message 2 of 8 , Sep 29, 2010
      • 0 Attachment
        Lucas Gonze wrote:
        >
        > I follow discussions here enough to know that versioning in RESTful
        > APIs has been much discussed, but not enough to understand all the
        > threads.
        >
        > Is there a write-up summarizing the issues?
        >

        Not that I know of. I won't summarize the issues, but I can list the
        positions:

        1) You don't need versioning in REST, just like there was no versioning
        required for image/gif changing from 87a to 89a, etc.

        2) Version the identifier, like application/x.foo-v2+xml

        3) Use the profile parameter, like RFC 3236

        4) If only client components care, leave it in the document, like
        DOCTYPE for text/html

        5) Version the URI, like /v1/foo vs. /v2/foo

        No further comment.

        -Eric
      • Tim Williams
        ... 6) I think it was Craig s suggestion to use a version http header (e.g. API-Version: 1.0) There s also an opinion out there that s a twist on option 1: 1a)
        Message 3 of 8 , Sep 29, 2010
        • 0 Attachment
          On Wed, Sep 29, 2010 at 3:45 PM, Eric J. Bowman <eric@...> wrote:
          > Lucas Gonze wrote:
          >>
          >> I follow discussions here enough to know that versioning in RESTful
          >> APIs has been much discussed, but not enough to understand all the
          >> threads.
          >>
          >> Is there a write-up summarizing the issues?
          >>
          >
          > Not that I know of.  I won't summarize the issues, but I can list the
          > positions:
          >
          > 1) You don't need versioning in REST, just like there was no versioning
          > required for image/gif changing from 87a to 89a, etc.
          >
          > 2) Version the identifier, like application/x.foo-v2+xml
          >
          > 3) Use the profile parameter, like RFC 3236
          >
          > 4) If only client components care, leave it in the document, like
          > DOCTYPE for text/html
          >
          > 5) Version the URI, like /v1/foo vs. /v2/foo

          6) I think it was Craig's suggestion to use a version http header
          (e.g. API-Version: 1.0)

          There's also an opinion out there that's a twist on option 1:

          1a) You don't need versioning if you're designing your media types well.

          That's just for completeness, there's no best answer.
          --tim
        • Lucas Gonze
          Thanks for the help, Tim and Eric. I d add one more point: moving away from URI construction to HATEOAS sometimes make versioning moot.
          Message 4 of 8 , Sep 29, 2010
          • 0 Attachment
            Thanks for the help, Tim and Eric.

            I'd add one more point: moving away from URI construction to HATEOAS
            sometimes make versioning moot.

            On Wed, Sep 29, 2010 at 12:53 PM, Tim Williams <williamstw@...> wrote:
            > On Wed, Sep 29, 2010 at 3:45 PM, Eric J. Bowman <eric@...> wrote:
            >> Lucas Gonze wrote:
            >>>
            >>> I follow discussions here enough to know that versioning in RESTful
            >>> APIs has been much discussed, but not enough to understand all the
            >>> threads.
            >>>
            >>> Is there a write-up summarizing the issues?
            >>>
            >>
            >> Not that I know of.  I won't summarize the issues, but I can list the
            >> positions:
            >>
            >> 1) You don't need versioning in REST, just like there was no versioning
            >> required for image/gif changing from 87a to 89a, etc.
            >>
            >> 2) Version the identifier, like application/x.foo-v2+xml
            >>
            >> 3) Use the profile parameter, like RFC 3236
            >>
            >> 4) If only client components care, leave it in the document, like
            >> DOCTYPE for text/html
            >>
            >> 5) Version the URI, like /v1/foo vs. /v2/foo
            >
            > 6) I think it was Craig's suggestion to use a version http header
            > (e.g. API-Version: 1.0)
            >
            > There's also an opinion out there that's a twist on option 1:
            >
            >   1a) You don't need versioning if you're designing your media types well.
            >
            > That's just for completeness, there's no best answer.
            > --tim
            >
          • mike amundsen
            For me, it helps to think about versioning is a _technique_ and not a goal or system property to be attained. Usually when talking about versioning we are
            Message 5 of 8 , Sep 29, 2010
            • 0 Attachment
              For me, it helps to think about versioning is a _technique_ and not a
              goal or system property to be attained.

              Usually when talking about "versioning" we are really trying to deal
              with the issue of modifiability at the system (arch) level. Fielding's
              dissertation does a good job of identifying "System Properties of Key
              Interest"[1] and one section deals with Modifiability[2] in general.

              Once I started thinking about versioning in this way, I was able to
              look to other techniques to improve the general modifiability of an
              implementation. And sometimes these other techniques (identified in
              2.3.4) made the use of versioning superfluous.

              [1] http://www.ics.uci.edu/~fielding/pubs/dissertation/net_app_arch.htm#sec_2_3
              [2] http://www.ics.uci.edu/~fielding/pubs/dissertation/net_app_arch.htm#sec_2_3_4

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


              #RESTFest 2010
              http://rest-fest.googlecode.com




              On Wed, Sep 29, 2010 at 16:32, Lucas Gonze <lucas.gonze@...> wrote:
              > Thanks for the help, Tim and Eric.
              >
              > I'd add one more point: moving away from URI construction to HATEOAS
              > sometimes make versioning moot.
              >
              > On Wed, Sep 29, 2010 at 12:53 PM, Tim Williams <williamstw@...> wrote:
              >> On Wed, Sep 29, 2010 at 3:45 PM, Eric J. Bowman <eric@...> wrote:
              >>> Lucas Gonze wrote:
              >>>>
              >>>> I follow discussions here enough to know that versioning in RESTful
              >>>> APIs has been much discussed, but not enough to understand all the
              >>>> threads.
              >>>>
              >>>> Is there a write-up summarizing the issues?
              >>>>
              >>>
              >>> Not that I know of.  I won't summarize the issues, but I can list the
              >>> positions:
              >>>
              >>> 1) You don't need versioning in REST, just like there was no versioning
              >>> required for image/gif changing from 87a to 89a, etc.
              >>>
              >>> 2) Version the identifier, like application/x.foo-v2+xml
              >>>
              >>> 3) Use the profile parameter, like RFC 3236
              >>>
              >>> 4) If only client components care, leave it in the document, like
              >>> DOCTYPE for text/html
              >>>
              >>> 5) Version the URI, like /v1/foo vs. /v2/foo
              >>
              >> 6) I think it was Craig's suggestion to use a version http header
              >> (e.g. API-Version: 1.0)
              >>
              >> There's also an opinion out there that's a twist on option 1:
              >>
              >>   1a) You don't need versioning if you're designing your media types well.
              >>
              >> That's just for completeness, there's no best answer.
              >> --tim
              >>
              >
              >
              > ------------------------------------
              >
              > Yahoo! Groups Links
              >
              >
              >
              >
            • William Martinez Pomares
              Totally agree with Mike. Side note: Reusability is an effect more than a need for modifiability, the actual part that helps is the loose coupling. Now, I would
              Message 6 of 8 , Sep 30, 2010
              • 0 Attachment
                Totally agree with Mike.
                Side note: Reusability is an effect more than a need for modifiability, the actual part that helps is the loose coupling.

                Now, I would like to add some of the techniques described seems just to identify versions, versioning requires a step further.
                Version identification is useful to avoid conflicts, to choose implementations or to validate. At the end of the day, if you have identified a version, you will still need to write specific code to handle it. That causes redundancy the most of the time, and as Zachman says, redundancy drives to chaos, system's entropy.

                When you don't need version identification simply because a new version will not break the system, you just achieved modifiability.
                All at all, it all depends on what is the change that creates a new version.

                Thanks, Mike, you just gave me an idea for a blog post on types of changes that require versioning, and how to solve them without version identification.

                William Martinez.
                --- In rest-discuss@yahoogroups.com, mike amundsen <mamund@...> wrote:
                >
                > For me, it helps to think about versioning is a _technique_ and not a
                > goal or system property to be attained.
                >
                > Usually when talking about "versioning" we are really trying to deal
                > with the issue of modifiability at the system (arch) level. Fielding's
                > dissertation does a good job of identifying "System Properties of Key
                > Interest"[1] and one section deals with Modifiability[2] in general.
                >
                > Once I started thinking about versioning in this way, I was able to
                > look to other techniques to improve the general modifiability of an
                > implementation. And sometimes these other techniques (identified in
                > 2.3.4) made the use of versioning superfluous.
                >
                > [1] http://www.ics.uci.edu/~fielding/pubs/dissertation/net_app_arch.htm#sec_2_3
                > [2] http://www.ics.uci.edu/~fielding/pubs/dissertation/net_app_arch.htm#sec_2_3_4
                >
                > mca
                > http://amundsen.com/blog/
                > http://twitter.com@mamund
                > http://mamund.com/foaf.rdf#me
                >
                >
                > #RESTFest 2010
                > http://rest-fest.googlecode.com
                >
                >
                >
              • mike amundsen
                William: Happy to be a catalyst . I m looking forward to another of your excellent blog posts, too. mca http://amundsen.com/blog/ http://twitter.com@mamund
                Message 7 of 8 , Sep 30, 2010
                • 0 Attachment
                  William:

                  Happy to be a catalyst<g>. I'm looking forward to another of your
                  excellent blog posts, too.

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


                  #RESTFest 2010
                  http://rest-fest.googlecode.com




                  On Thu, Sep 30, 2010 at 11:54, William Martinez Pomares
                  <wmartinez@...> wrote:
                  > Totally agree with Mike.
                  >  Side note: Reusability is an effect more than a need for modifiability, the actual part that helps is the loose coupling.
                  >
                  > Now, I would like to add some of the techniques described seems just to identify versions, versioning requires a step further.
                  > Version identification is useful to avoid conflicts, to choose implementations or to validate. At the end of the day, if you have identified a version, you will still need to write specific code to handle it. That causes redundancy the most of the time, and as Zachman says, redundancy drives to chaos, system's entropy.
                  >
                  > When you don't need version identification simply because a new version will not break the system, you just achieved modifiability.
                  > All at all, it all depends on what is the change that creates a new version.
                  >
                  > Thanks, Mike, you just gave me an idea for a blog post on types of changes that require versioning, and how to solve them without version identification.
                  >
                  > William Martinez.
                  > --- In rest-discuss@yahoogroups.com, mike amundsen <mamund@...> wrote:
                  >>
                  >> For me, it helps to think about versioning is a _technique_ and not a
                  >> goal or system property to be attained.
                  >>
                  >> Usually when talking about "versioning" we are really trying to deal
                  >> with the issue of modifiability at the system (arch) level. Fielding's
                  >> dissertation does a good job of identifying "System Properties of Key
                  >> Interest"[1] and one section deals with Modifiability[2] in general.
                  >>
                  >> Once I started thinking about versioning in this way, I was able to
                  >> look to other techniques to improve the general modifiability of an
                  >> implementation. And sometimes these other techniques (identified in
                  >> 2.3.4) made the use of versioning superfluous.
                  >>
                  >> [1] http://www.ics.uci.edu/~fielding/pubs/dissertation/net_app_arch.htm#sec_2_3
                  >> [2] http://www.ics.uci.edu/~fielding/pubs/dissertation/net_app_arch.htm#sec_2_3_4
                  >>
                  >> mca
                  >> http://amundsen.com/blog/
                  >> http://twitter.com@mamund
                  >> http://mamund.com/foaf.rdf#me
                  >>
                  >>
                  >> #RESTFest 2010
                  >> http://rest-fest.googlecode.com
                  >>
                  >>
                  >>
                  >
                  >
                  >
                  >
                  > ------------------------------------
                  >
                  > Yahoo! Groups Links
                  >
                  >
                  >
                  >
                • Philippe Mougin
                  ... I concur. Defining a service versioning strategy is often perceived, by companies I m doing SOA consulting for, as the goal, as Mike points out, because it
                  Message 8 of 8 , Sep 30, 2010
                  • 0 Attachment
                    Le 29 sept. 2010 à 23:07, mike amundsen a écrit :

                    > For me, it helps to think about versioning is a _technique_ and not a
                    > goal or system property to be attained.
                    >
                    > Usually when talking about "versioning" we are really trying to deal
                    > with the issue of modifiability at the system (arch) level. Fielding's
                    > dissertation does a good job of identifying "System Properties of Key
                    > Interest"[1] and one section deals with Modifiability[2] in general.
                    >
                    > Once I started thinking about versioning in this way, I was able to
                    > look to other techniques to improve the general modifiability of an
                    > implementation. And sometimes these other techniques (identified in
                    > 2.3.4) made the use of versioning superfluous.

                    I concur. Defining a service versioning strategy is often perceived, by companies I'm doing SOA consulting for, as the goal, as Mike points out, because it is identified as the only means to manage service evolution. This isn't a surprise, as people have been so much exposed to distributed technologies that induce strong coupling. Often, I then try to convey the idea that "what is central to your needs isn't to define a versioning strategy, but to define a strategy that will let you avoid using versioning whenever possible. You'll want to version only in last resort." (here, the goodness of REST and other practices such as using dynamic data structures in the clients and services implementations kick in).

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