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 from 2004 claiming there is no actual standard, and only best practices. Any better solutions? How do you solve WS versioning?

Problem Description

System A

Client

class SystemAClient{
    SystemBServiceStub systemB;
    public void consumeFromB(){
        SystemBObject bObject = systemB.getSomethingFromB(new SomethingFromBRequest("someKey"));

    }
}

Service

class SystemAService{
    public SystemAObject getSomethingFromA(SomethingFromARequest req){
        return new SystemAObjectFactory.getObject(req);
    }
}

Transferable Object

Version 1

class SystemAObject{
     Integer id;
     String name;
     ... // getters and setters etc;
}

Version 2

class SystemAObject{
     Long id;
     String name;
     String description;
     ... // getters and setters etc;
}

Request Object

Version 1

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

}

Version 2

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

}

System B

Client

class SystemBClient{
    SystemAServiceStub systemA;
    public void consumeFromA(){
        SystemAObject aObject = systemA.getSomethingFromA(new SomethingFromARequest(1));
        aObject.getDescription() // fail point
        // do something with it...
    }
}

Service

class SystemBService{
    public SystemBObject getSomethingFromB(SomethingFromBRequest req){
        return new SystemBObjectFactory.getObject(req);
    }
}

Transferable Object

Version 1

class SystemBObject{
     String key;
     Integer year;
     Integer month;
     Integer day;

     ... // getters and setters etc;
}

Version 2

class SystemBObject{
     String key;
     BDate date;
     ... // getters and setters etc;
}

class BDate{
     Integer year;
     Integer month;
     Integer day;
     ... // getters and setters etc;

}

Request Object

Version 1

class SomethingFromBRequest {
     String key;
     ... // getters and setters etc;
}

Version 2

class SomethingFromBRequest {
     String key;
     BDate afterDate;
     BDate beforeDate;
     ... // getters and setters etc;
}

Fail Scenarios

If a System A client of version 1 calls a System B service of version 2 it can fail on:

• missing methods on SystemBObject (getYear(), getMonth(), getDay())
• Unknown type BDate

If a System A client of version 2 calls a System B service of version 1 it can fail on:

• Unknown type BDate on the SomethingFromBRequest (A client uses a newer B request object that B version 1 doesn't recognize)
• If the System A client is smart enough to use version 1 of the request object, it can fail on missing methods on the SystemBObject object (getDate())

If a System B client of version 1 calls a System A service of version 2 it can fail on:

• Type missmatch or overflow on SystemAObject (returned Long but expected Integer)

If a System B client of version 2 calls a System A service of version 1 it can fail on:

• Type missmatch or overflow on SystemARequest (request Long instead of Integer)
• If the request passed somehow, casting issues (the stub is Long but the service returns an Integer not nessecarily compatible in all WS implementations)

Possible solutions

1. Use numbers when advancing versions: e.g. SystemAObject1, SystemBRequest2 etc but this is missing a an API for matching source / target version
2. In the signature, pass XML and not objects (yuck, pass escaped XML in XML, double serialization, deserialization / parsing, unparsing)
3. Other: e.g. does Document/literal / WS-I has a remedy?

Answer 1

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 2

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 3

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 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