[prev in list] [next in list] [prev in thread] [next in thread] 

List:       soap-user
Subject:    Thoughts on API versioning...
From:       "Denis Haskin" <dwhaskin () earthlink ! net>
Date:       2001-02-28 20:26:42
[Download RAW message or body]

(This is a somewhat larger issue than SOAP but I'm hoping I might get
some good feedback from this group.  Recommendations on better places to
discuss this would be welcome.)

I'm wrestling with how to handle API versioning in a sort-of-RPC
situation.  It's currently HTML and HTTP but will move to XML on HTTP
and possibly SOAP.

In the current setup, a client makes a request of the server using an
HTTP GET.  The version of the API is specified by an element of the
URL's path.  For example:

    GET /svc/get_item.pl?param=foo
    GET /svc2/get_item.pl?param=foo

are two calls where get_item.pl are largely the same function, but in
the particular the format of the returned HTML is different.

We're moving to an implementation-independent URL scheme, something like

    GET /Service/GetItem?param=foo
and I'm trying to decide where best to specify version information, if
needed.

I can see 4 or more places for it:
-- in the path, as it has been (e.g. /Service/v3/GetItem or some such
thing)
-- as a parameter (e.g. /Service/GetItem?version=3)
-- as an HTTP header (e.g. "X-API-Version: 3.0")
-- or even someplace else.

I actually expect that specific version info won't usually be needed,
but that the server will if necessary modify it's behavior based on the
HTTP "User-agent:" header (or maybe a non-standard header that tells us
the client's version).  However, there certainly might be cases where a
client will need to specify an API version, independent of its own
version.

My gut tells me it should be done as an HTTP header, but I don't have
any good reasons for it, and that's the method that would require more
work on the part of another development team (of course).

I find it hard to believe I'm the first person to encounter this design
question, but fairly exhaustive web-searching hasn't revealed much
discussion of this kind of issue.  Like I said, any suggestions would be
appreciated, or pointers to more appropriate mailing lists/newsgroups.

Thanks,

dwh

[prev in list] [next in list] [prev in thread] [next in thread]