What are your WebService Versioning best practices?

Question

We have 2 separate products that need to communicate with each other via web services. What is the best-practice to support versioining of the API?

I have this article

Answer 1

The solution is to avoid incompatible changes to your types.

Take for example, SystemBObject. You describe "version 1" and "version 2" of this type, but they are not the same type at all. A compatible change to this type involves only Adding properties, and not changing the type of any existing properties. Your hypothetical "Version update" has violated both of those constraints.

By following that one guildeline, you can avoid ALL of the problems you described.

Therefore, if this is your type definition in version 1

class SystemBObject{  // version 1
    String key;  
    Integer year;  
    Integer month;  
    Integer day;  

    ... // getters and setters etc;  
}  

Then, this cannot be your type definition in v2:

// version 2 - NO NO NO 
class SystemBObject{ 
    String key; 
    BDate date; 
    ... // getters and setters etc; 
} 

...because it has eliminated existing fields. If that is the change you need to make, it is not a new "version", it is a new type, and should be named as such, both in code and in the serialization format.

Another example: If this is your existing v1 type :

class SomethingFromARequest {   
    Integer requestedId;   
    ... // getters and setters etc;      
}   

... then this is not a valid "v2" of that type:

class SomethingFromARequest {   
    Long requestedId;   
    ... // getters and setters etc;      
}   

...because you have changed the type of the existing property.

These constraints are explained in much more detail a mostly technology-neutral way in Microsoft's Service Versioning article.

---

Aside from avoiding that source of incompatibility, you can and should include a version number in the type. This can be a simple serial number. If you are in the habit of logging or auditing messages, and bandwidth and storage space is not a problem, you may want to augment the simple integer with a UUID to identify an instance of each unique version of a type.

Also, you can design forward-compatibility into your data transfer objects, by using lax processing, and mapping "extra" data into an "extra" field. If XML is your serialization format, then you might use xsd:xmlAny or xsd:any and processContents="lax" to capture any unrecognized schema elements, when a v1 service receives a v2 request (more). If your serialization format is JSON, with its more open content model, then this comes for free.

Answer 2

I know this is late to the game, but I've been digging into this issue rather deeply. I really think the best answer involves another piece of the puzzle: a service intermediary. Microsoft's Managed Services Engine is an example of one - I'm sure others exist as well. Basically, by changing the XML namespace of your web service (to include a version number or date, as the linked article mentions), you allow the intermediary the capability to route the various client calls to the appropriate server implementations. An additional (and, IMHO, very cool) feature of MSE is the ability to perform policy-based transformation. You can define XSLT transforms that convert v1 requests into v2 requests, and v2 responses into v1 responses, allowing you to retire the v1 service implementations without breaking client implementations.

Answer 3

I prefer the Salesforce.com method of versioning. Each version of the Web Services gets a distinct URL in the format of:

http://api.salesforce.com/{version}/{serviceName}

So you'll have Web Service URLs that look like:

http://api.salesforce.com/14/Lead

http://api.salesforce.com/15/Lead

and so on...

With this method, you get the benefits of:

1. You always know which version you're talking to.

2. Backwards compatibility is maintained.

3. You don't have to worry about dependency issues. Each version has the complete set of services. You just have to make sure you don't mix versions between calls (but that's up to the consumer of the service, not you as the developer).

Answer 4

I think something else to keep in mind is your client base, are you publishing this service publicly, or is it restricted to a set of known agents?

I'm involved in the latter situation, and we've found it's not that difficult to solve this via simple communication / stakeholdering.

Though it's only indirectly related to your question, we've found that basing our versioning number on compatibility seems to work quite well. Using A.B.C as an example...

• A: Changes which require recompilation (breaks backwards compatibility)
• B: Changes which do not require recompilation, but have additional features not available without doing so (new operations etc.)
• C: Changes to the underlying mechanics that do not alter the WSDL