I am currently developing a new RESTful application in our company, and I want to do my job as properly as possible. And as many more RESTful applications/services will follow, I am currently reading up on the topic as-I-go. Also, out of experience, I know that APIs will evolve over time, and the need to version them is not something new.
At the very beginning of my quest, I came to an answer on StackOverflow discussing just that. The answer itself, pointed me to both the RFC for Media Types. I am still in the process of reading it in all it's glory, but so far, the "personal" or even "special" sub-type trees seem to fit my needs perfectly. This let's me explicitly define the media type I am communicating with my client.
In parallel, the SO answer pointed me also indirect;ly to a section about versioning in the "Nobody Understands REST or HTTP" document.
All in all, I find the solution with the custom sub-type tree and the version parameter very appealing.
Unfortunately, Flask is not yet able to parse this properly. As far as I can see, this could be handled transparently inside MIMEAccept by only relaxing the "accept_json" logic to represent a general "does the client understand JSON" question, and adding a few extra accessors which are more precise.
I am not yet 100% certain how this could look like, but if you want I would be willing to look into it, and make a proposal via pull-request?
It'd be great if Flask.Request.get_json was a little smarter about what it considers JSON. Right now it's just 'application/json', but ideally it should understand MIME types matching 'application/(.++)?json' (such as 'application/vnd.collection+json' or 'application/vnd.mycompany.myproject.mytype+json'). This looks like a good first step, after that maybe recognize and ignore parameters too.
This should be implemented in werkzeug (https://github.com/mitsuhiko/werkzeug/) as part of the Request class