### XFire Home Bug/Issue Reporting Download FAQ Get Involved License News Stack Comparison Support User's Guide XFire Team ### M5 Javadocs Reports ### M6-SNAPSHOT Javadocs Reports ### Developers Developer Space CVS Building Architecture Interesting Projects Release Process | This page attempts to cover basic versioning patterns in web services. A lot of these patterns can be mixed and matched to provide the best combination. ## No Version Pattern Description: Some people may choose to not worry about versioining at all. While, not strictly a versioning pattern, it is helpful to mention this to know the upsides and downsides. Pros: Easy. Cons: Old clients built on the previous version will break. When to use: when you have total control over every client using your service. References: None. ## Namespace Pattern Description: Namespaces can be used to determine different type versions. Your first service revision may have a target namespace of "urn:company:service:v1" and each subsequent major revision will have an increased version number. Knowing the version of your xml documents, will tell you which version of the service to invoke. Example: Say you want to move from a decimal type for prices (which allows a minimum of 18 digits beyond the decimal point) to a more approciate price type which you created which only allows 2 digits beyond the decimal: Old Version:
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      <soap:Body>
        <Price xmlns="urn:company:service:v1">3.333333</Price>
      </soap:Body>
    </soap:Envelope>
New Version
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      <soap:Body>
        <Price xmlns="urn:company:service:v2">3.33</Price>
      </soap:Body>
    </soap:Envelope>
Because of the namespace change you know that the first request is still acceptable even though it doesn't conform to your latest schema. Services following this pattern: Amazon Pros: Takes advantage of XML namespaces, works well with backwards incompatabile schema changes. Cons: Doesn't take advantage of XML schema extensibility. When to use: References: Designing Extensible, Versionable XML Formats (Very very good) Versioning XML Vocabularies ## Version Parameter Pattern Description: Including a version number in the request will help you determine how to process the request and what kind of response to return. Examples: Example 1 (Header):
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      <soap:Header>
        <Version xmlns="urn:company:service">340</Version>
      </soap:Header>
      <soap:Body>
        ....
      </soap:Body>
    </soap:Envelope>
Example 2 (Body):
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      <soap:Body>
        <SomeRequest xmlns="urn:company:service">
          <Version>340</Version>
          ....
        </SomeRequest>
      </soap:Body>
    </soap:Envelope>
Services following this pattern: eBay (header) Pros: Uses XML schema extensibility. Cons: Does not work well with incompatabile schema changes, doesn't take advantage of XML namespaces, requires users to pass the parameter in ever request. When to use: References: http://dev4net.com/blog/archive/2004/12/03/962.aspx eBay API Documentation ## New Endpoint Pattern Description: The new endpoint pattern is very close to the version paramter pattern. The only difference is that instead of putting the version being accessed into the request, it becomes part of the URL being invoked. Example:
    http://example.com/service/v1
    http://example.com/service/v2
Services following this pattern: JIRA? Pros: Uses XML schema extensibility. Cons: Requires users to update their invocation url each you update versions, Does not work well with incompatabile schema changes, doesn't take advantage of XML namespaces. When to use: References: http://blogs.msdn.com/dareobasanjo/archive/2004/11/30/272113.aspx