On 24/09/2013 8:35 AM, Richard Newman wrote:
>> This also has the benefit operationally of being able to run only the
>> highest version of the 1.X series and knowing that it'll talk compatibly to
>> all the 1.X clients. If you're using integer versions, you either have to
>> maintain semantically unclear maps in the backend, or maintain all the
>> versions.
>
> Pretty much that's equivalent to putting "1" in the URL, and using "1.3" for
> docs, so I'm on board with that. If the wire protocol (including responses)
> is back-compatible, the client doesn't need to tell the server explicitly
> that it's a 1.3 client.
I'm +1 on including the full MAJOR.MINOR in the URL, since it reduces
the chance of miscommunication.
Remember that we don't just have to worry about old clients talking to
new servers - with third-party installs of our products in the wild,
there's also the possibility of new clients talking to old servers.
Brian made a good point in the standup today: do we expect to change
this so much that we'll be introducing many minor version increments?
If not then maybe it's cleaner to just use a major version number.
> My only concern with the version-first idea: it can introduce some cost in
> deployment and software management. Nobody wants to maintain 30 different
> entry points to mostly-the-same code, just because you revved a version
> number to change some API contract. Ideally one can segment the URL space (or
> use back-compatibility somehow) to allow for sensible revving:
>
> foo.com/1/users/2/eat
> => {v: 5,
> name: "bar"}
*cough* HATEOAS *cough* :-)
I strongly dislike the thought of clients piecing together URLs by
selecting the version of each resource that they're interested in.
IMHO this more resource-driven kind of API is better versioned using
Accept headers or similar.
Since our APIs small, infrequently changing, and have more of an RPC
feel about them, a single version number at the beginnig of the URL
space makes sense to me:
https://<service-endpoint>/<version>/<instructions>
Cheers,
Ryan
_______________________________________________
Sync-dev mailing list
[email protected]
https://mail.mozilla.org/listinfo/sync-dev
