Excerpts from Bill Peck's message of 2013-02-21 23:57:17 +1000:
Second relates to Provisional period for the API. Do you see any
drawback to versioning the rest url?
For example:
POST /v1/recipes/(/recipe_id/)/tasks/(/task_id/)/results/
This would be more flexible if we ever need to make changes, and both a
v1 and v2 api could be made available at the same time.
We could, but I don't think it's necessary.
HTTP already gives us ways to deal with most kinds of changes,
especially if you think of it in terms of resources, not actions. Some
examples...
If you want to allow a new method on a resource, or add a new resource:
just add it, nothing breaks.
If you want to accept a new data format as input: clients should already
be sending Content-Type in the requests, just allow a new one.
If you want to add a new data format as output: use content negotiation
(the Accept header in the request) to pick which format the client wants
to see.
If you want to change the semantics of an existing resource: probably
this means that you are really talking about a *different* resource, so
just use a different path.
If you *really* want to change the semantics of an existing resource:
worst case, the client can use a query string argument to select the
behaviour they want. But this is a bit messy.
If you want to move a resource to a different path: for GET requests you
can return a redirect. For everything else, just don't do it.
If you want to drop support for something: well, there is never
a backwards-compatible way to do this no matter what your interface is,
so just don't do it. The best you can do is document it as deprecated
for a while, and eventually remove it (return 410 Gone) and hope nobody
was still using it.
--
Dan Callaghan <dcallagh(a)redhat.com>
Software Engineer, Infrastructure Engineering and Development
Red Hat, Inc.