Service Versioning

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Service Versioning

Mark Nottingham-2

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/


Reply | Threaded
Open this post in threaded view
|

Re: Service Versioning

Mark Baker

Do you have a use case for this, Mark?

On 4/27/06, Mark Nottingham <[hidden email]> 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/
>
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Service Versioning

Mark Nottingham-4

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 <[hidden email]> 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
[hidden email]




Reply | Threaded
Open this post in threaded view
|

Re: Service Versioning

Philippe Le Hegaret
In reply to this post by Mark Nottingham-2
On Thu, 2006-04-27 at 13:12 -0700, Mark Nottingham wrote:
> <resource introduced="/revision/1">
>     <method name="GET">
>       ...
>     </method>
>     <method name="POST" introduced="/revision/2">
>       ...
>     </method>
> </resource>

Wouldn't you be able to resolve your use case by using dated links and a
latest version link? Or is it important for you to follow the trail of
revisions (ie you would need a "previous version" link).

Philippe


signature.asc (198 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Service Versioning

Mark Nottingham-4

Do you mean in the service URIs themselves, or in the revision links?


On 2006/04/28, at 12:02 PM, Philippe Le Hegaret wrote:

> On Thu, 2006-04-27 at 13:12 -0700, Mark Nottingham wrote:
>> <resource introduced="/revision/1">
>>     <method name="GET">
>>       ...
>>     </method>
>>     <method name="POST" introduced="/revision/2">
>>       ...
>>     </method>
>> </resource>
>
> Wouldn't you be able to resolve your use case by using dated links  
> and a
> latest version link? Or is it important for you to follow the trail of
> revisions (ie you would need a "previous version" link).
>
> Philippe
>

--
Mark Nottingham
[hidden email]