APIVersioning
From MashupCamp
Discuss this topic in a threaded discussion
API Versioning & Backwards Compatability
NoteTaker: TomOrtega
Problems
1 big legacy WSDL with every function\use case
Transport technology
Synchronous/Asynchronous
Changing attribute count and types
Can't support all versions eternally, i.e. shrinkwrap software can function eternally
No COM-like "Here I am and here's what I can do" with SOAP
Methods / Tips Tricks
Passing Version numbers as input/url
Support a revolving time frame of versions (i.e. 1 year's worth of versions)
Make as much as you can optional (min_occurs = 0)
XSD documentation
Version by Call, regardless of WSDL version
1 keeper of the schema for a "unified" voice
Program logic to still accept older values (continents) when new values are preferred (countries)
Communicate "This update is going to break this call" when you get them
Plan to help customers not have to update with every version
Client libraries updates should follow after wsdl updates on a regular timeframe (i.e. 2 weeks)
Sandbox environment - tuned down versions of production environments, but preview features
Rather than changing parameter type, try adding a second parameter and make the pair the unique value
When you make "safe" changes, still communicate the changes in advance
Go the extra mile when communicating changes (Pick up the phone if you have to!)
Provide tools to the users to handle self-testing
Minimize patches
Version by methods
Try to support every feature, even the "non-supported" ones
You can't hide features from the users
URL structures to save SOAP processing
Open an "XML" version of the call and internally rewrap in a SOAP call and use the same engine
Expire developer key as a possible way to ensure users' contact info is up to date
Make sandbox environments a lot stricter sooner as a way to forewarn
Getting Started
REST style with simple http requests and query strings for getting data
Think ahead when creating an API, since people will come to depend on an API regardless of how "bad" you later find it
Take a look at flickr
MicroFormats - http://wiki.mashupcamp.com/index.php/MicroFormatsAPIs
