API versioning via Accept header

[pyeve]

API versioning via Accept header

[nicolaiarocci]

Yes, interesting. I like keeping URIs clean too. Will brainstorm a little and get back to you.

[nicolaiarocci]

Support for dynamic versioning implies that the API is aware of different schemas (in Eve jargon, one DOMAIN per version). And that's not taking global configuration settings (RESOURCE_METHODS, CACHE_CONTROL, etc) into account. It's doable, at the inevitable cost of configuration complexity. A couple options come to mind:

Multiple, isolated, settings files, one per version. Users could always use imports to easily replicate common settings.

Or,

One file as it is now, but split the version configuration somehow, maybe with a dictionary. Something like:

{
 'v1': {
    RESOURCE_METHODS: ['GET'], 
    ...
    DOMAIN: {...},
 }
{
 'v2': {
   RESOURCE_METHODS: ['GET'],
   ...
   DOMAIN: {...},
 }
}

It gets simpler if we'd only allow for domain deltas between versions:

DOMAIN: {
  'v1': {...},
  'v2': {...},
}

Of course both designs could be merged:

{
 'v1': 'settings-v1.py',
 'v2': 'settings-v2.py'
}

The trick is to balance flexibility with complexity. Mind you, I'm just brainstorming in the open, so to speak.

[nicolaiarocci]

Also, I should add that I'm not too fond of API versioning. I believe that clients should be intelligent enough to deal with API updates transparently, especially since Eve-powered API support HATEOAS.

[nicolaiarocci]

On second thought I believe that different API versions should be totally isolated instances since so many things would/could be different between versions: caching, URIs, schemas, validation, and so on. For example, since URL mappings are loaded at startup, dynamically handling different mappings would be impossible without a rewrite of the core. Also, URI versioning (http://api.example.com/v1/...), which is already supported, is build around isolated API instances.

I'm keeping this on hold for the time being.