Re: Service Versioning

Sure.

Imagine I design an "abstract" service that is going to be deployed  
in several places. E.g., a data store API that has different  
deployments, each with a different type of data (movies, sports,  
whatever). The interface exposed by the resources on each site is the  
same, but has different semantics.

Let's say for the sake of simplicity that it starts with one resource;
a)  http://{hostname}/foo

It has a description available at:
b)  http://www.example.com/data.wadl

The service is deployed to the different sites. Clients are written.

Later, a new resource is added* to the standard API;
c)  http://{hostname}/bar
and the description (b) is updated to include (c).

Some instances of the API are upgraded to include (c); others lag a bit.

It would really be nice to not have to fork the description at (b),  
since these changes are backwards-compatible. However, the client  
doesn't have any way to distinguish the different revisions of the  
API. So, if the description indicates when features were added, and  
the client can query the service to find out what revision it  
implements, all is well.

Of course, they can also optimistically try to fetch (c) and see what  
happens (and in any case, they have to be ready to handle that  
failure), but if we have a description, it would be nice to capture  
this information there, so the client can avoid trying to use  
something that isn't there, assuming it has a way to find out the  
revision that they're interacting with.

Part of my head says that this isn't very hypertext-is-the-engine-of- 
application-state-ish, but I'm not sure I buy that. If they  
dereference the "introduced" URI and get a description of what's  
available, they are using hypertext as a way to figure out what  
resources are available; at any rate, a machine-to-machine  
interaction (for the forseeable future) is going to be less like  
human navigation at runtime (but still will be at design time).

* This could be any backwards-compatible change; e.g., new methods  
supported, new HTTP functions, new representations, backwards- 
compatible format changes.



On 2006/04/28, at 9:38 AM, Mark Baker wrote:

>
> Do you have a use case for this, Mark?
>
> On 4/27/06, Mark Nottingham <mnot@mnot.net> wrote:
>>
>> Just thinking out loud -- not sure if this is a good idea or not.
>>
>> What if components were labelled with an indication of the revision
>> of the service that they were introduced with?
>>
>> E.g.,
>>
>> <resource introduced="/revision/1">
>>     <method name="GET">
>>       ...
>>     </method>
>>     <method name="POST" introduced="/revision/2">
>>       ...
>>     </method>
>> </resource>
>>
>> with rules for appropriate defaulting, etc. "introduced" probably
>> isn't the best name, but gets the idea across; the value should be a
>> URI-reference.
>>
>> This would allow clients to query the service for what revision it
>> implements, and then know what (backwards-compatible) changes are
>> implemented; it wouldn't have to optimistically try to POST, for
>> example.
>>
>> In doing so, backwards-compatible changes (e.g., adding methods,
>> adding representations, adding resources, adding optional query args)
>> could be layered into descriptions without losing information about
>> when they were introduced.
>>
>> Thoughts?
>>
>> --
>> Mark Nottingham     http://www.mnot.net/
>>
>>
>>
>
>
>

--
Mark Nottingham
mnot@yahoo-inc.com

Received on Friday, 28 April 2006 17:28:33 UTC