Re: REST API: version numbers
Ralf Schlatterbeck <[email protected]>
| Newsgroups | gmane.comp.bug-tracking.roundup.devel |
|---|---|
| Message-ID | <[email protected]> |
On Tue, Mar 05, 2019 at 11:11:49PM -0500, John P. Rouillard wrote: > I think implementing a query parameter to control the version is > similar to @template. So .../rest/data/issue/1?@version=1 is > better. It may also be cleaner to implement when we have multiple > versions. > > The "correcter" way would be to set the version in the Accept header > in some form. However controlling the HTTP headers from a browser is > difficult. By supporting ?@version=1 somebody investigating the rest > interface in a browser could enter: > > rest/data/issue/21?@version=1 > rest/data/issue/21?@version=2 > > and see the different output. (This is the same reason for supporting > .json or .xml at the end of the url to control the returned data format.) > > I think version 0 is fine. The question is what form should the > version take? Should it be 0.0, or just 0. In X.y versioning would > mean that any client that understands version X.0 would be able to > understand version X.1 or newer. Compare to HTTP 1.0 vs 1.1. A version > 0.3 client could understand a version 0.99 response but might not > understand a 1.0 response. OK, it currently *is* 1 and I'd leave it at that. I'm fine with only a one-level version identifier, i.e. 0 not 0.0. Concerning ignoring fields in a response that are unknown: I'd specify up front that clients should ignore parameters they don't know about. If we ever introduce parameters that need to be understood by the client to process correctly I'd go for a new major version number. Ralf Ralf -- Dr. Ralf Schlatterbeck Tel: +43/2243/26465-16 Open Source Consulting www: http://www.runtux.com Reichergasse 131, A-3411 Weidling email: [email protected]