A letter in the mailbag this week:
So one thing I noticed when performing some test queries from the browser is that at first I got a couple of "No rule matched" errors until I decided to include the "20150623" part (a date?) in the query URL.
I didn't see a reference to this string in the intro docs. Is this an API version identifier? If so, where are allowable values documented?
My correspondant's intuition is correct - that eight digit number at the start of the URL path in a query to OneMusicAPI is a version number. Each version is named after a YYYYMMDD timestamp, decided during development time - most often it's the timestamp for one of the development milestones that contribute to an overall new release of OneMusicAPI.
When do we decide to add versions? We do this whenever a change is made to either the way requests are
made, or how responses are formatted. If we didn't have the version identifier, and we changed the way,
say, release/ returns release information, existing clients would begin to fail and would
have to change their code. Not good!
So the version segment allows us to continue serving data in a consistent way, whilst also delivering new features to those that need them.
There are some classes of change where we don't add a version. For example, if a new request parameter
is added and there's no change to the formatting of responses, this won't cause problems for clients.
mustInc was an example of
this.
But generally, we err on the side of caution. This is important, because one of the core tenets of OneMusicAPI is to provide a reliable, available abstraction layer above the freely available music metadata APIs.
To that end, we continue to support existing API versions while customers are using them. Once we have moved all customers to newer versions, we will remove the version - while there's no added cost in keeping them running if no-one is using them, it does make development level tasks more complicated with more tests to run, and so on.
For reference, the older, addressable, versions are listed here.
Here's to many more versions!
Thanks to Jens Rost who made the the image above available for sharing.
