Versioning of the API spec?

beetbox / aura

music library REST API

http://auraspec.rtfd.org/

75 stars 9 forks source link

Versioning of the API spec? #32

Open mgoltzsche opened 7 months ago

mgoltzsche commented 7 months ago

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 commented 7 months ago

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.