Versioning the API

[jkeifer]

It is best practice to create API versions so changes will not break existing clients.

The preferred way to implement versions is with a version tag in the request header:

GET /bookings/ HTTP/1.1
Host: example.com
Accept: application/json; version=1.0

More details can be found:
http://www.django-rest-framework.org/api-guide/versioning/
http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http#i_want_my_api_to_be_versioned
https://github.com/interagent/http-api-design/blob/master/en/foundations/require-versioning-in-the-accepts-header.md

[lbross]

This appears to be a property of the HttpWebRequest object. Let me know when you have an endpoint to test.

https://msdn.microsoft.com/en-us/library/system.net.httpwebrequest.accept(v=vs.100).aspx

[jkeifer]

@lbross I have a "versioned" endpoint at api/rest/api-version/ on the test instance. To test the version, first GET that endpoint without any changes to your accept header. You should get 0.2 as the response.

Then try sending the version 0.1 in the accept header, like this (assuming a JSON request):

Accept: application/json; version=0.1

You should then get 0.1 as the response.

Right now none of the endpoints are versioned, but as soon as I get confirmation from you that you can pass the version this way then I will start versioning everything. I will keep everything as-in on version 0.1, and any breaking changes will get implemented with higher version numbers. I'm working on a better way to track versions, and will likely implement some sort of change lot help keep versioning organized.

The version will default to the latest version (hence why you get 0.2 without supplying a version number above), so if you don't supply it you will always get the latest API version.

Note that currently if a version is supplied with a request is checked against valid versions and if the value supplied is not in that list an error will be returned (the current valid versions are just 0.1 and 0.2). I am unsure if this is the best behavior or not; if you have any ideas about this please let me know. The best alternative I could come up with would be to default to the latest version of the API if a specified version is invalid; I think I prefer raising an error to possibly--and silently--performing unexpected behavior.

[lbross]

The 'Accept' property of the HttpWebRequest object allows me to set this in the header. The api is responding as @jkeifer indicated. The api requires an application specification in the 'Accept' property in addition to the version number. Please update this issue as the version is added to an endpoint and I will update the PC-BAGIS code.