Set up API versioning

[leesharma]

Unversioned production APIs = sad, even if they are mostly for internal use.

I'll probably use the request header for this. Any die-hard URL-versioning advocates out there?

[leesharma]

Thoughts on our API Versioning Strategy

The four main options for API versioning are:

1. URL-based (ex. https://example.com/api/v1/resource/endpoint)
   • pros: dead simple, easy to experiment in browser
   • cons: can't version individual endpoints (only whole API), semantically messy (what's a version doing in the URL?)
2. Query-param based (ex. https://example.com/api/resource/endpoint?v=1)
   • pros: easy to experiment in browser, can version individual endpoints
   • cons: ugly and messy 😬
3. Custom header (ex. curl -Hapi-version v1 https://example.com/api/resource/endpoint)
   • pros: keeps metadata out of the url, can version individual endpoints
   • cons: unexpected custom header, kind of uncommon, hard to experiment in browser
4. Accept header (ex. curl -Haccept application/vnd.progressreport.v0 https://example.com/api/resource/endpoint)
   • pros: common method (so less confusing), keeps metadata out of the url, can version individual endpoints
   • cons: maybe confusing for new programmers, hard to experiment in browser

I think the Accept header (# 4) is the best route to go here.

Major benefits:

• Semantically nice (URL describes resources and endpoints, not misc. meta-information)
• Can version each endpoint independently instead of versioning the whole API. Given how closely we're mapping endpoints with views, I think this will be useful.

Major downsides:

• Harder to interact with in the browser (since we can't send Accept headers there)
• A little harder to test

Ways to mitigate downsides:

1. Default to the current API version (this will let us play around in the browser). This is kind of how GitHub handles it.
2. Add interactive documentation (ex. SwaggerUI) that lets us select accept headers in the browser (re: Add API docs #5)
3. (?) Add query parameter versions or something automatically with a decorator? This would let us visit https://progress-report-server.herokuapp.com/states/ohio?v=0.0.1 in the browser, even if we recommend acceptance headers for actual development. It would also allow us to maintain our independently versioned endpoints. I'm not sure having 2 options is a great idea, but it could be a good compromise.