Versioning of the API spec?

[mgoltzsche]

trafficstars

How is the AURA API versioned? I already noticed that the old beets web API is not versioned. Unfortunately, that also seems to be the case with the new AURA API, isn't it?

There are two common ways of versioning REST APIs:

• The text book way: specifying the version as part of the path prefix, e.g. /aura/v1/tracks.
• Specifying the version as part of the Content-Type which simplifies supporting multiple API versions at the same time and negotiating versioning with the clients.

[sampsyo]

This is a great point; thanks for bringing it up. It seems like I never actually wrote the down anywhere, but my original idea was your "textbook" suggestion—basically, everything the spec currently specifies is supposed to be hosted under a top-level path like /aura/1 or similar.

But I'm also open to the content-negotiation style… I've never used an API that uses that style! Clearly, we should pick one and actually specify it here.