speedruncomorg / api

REST API Documentation for speedrun.com
346 stars 36 forks source link

Breaking changes without incrementing the API version #141

Open exodustx0 opened 2 years ago

exodustx0 commented 2 years ago

From the README:

The API is versioned, the version is reflected in the URL you use. The API root, https://speedrun.com/api will redirect you to the current version. We promise to do our best to never break a once published version of our API (sometimes we extend the current API with new information, but we will not change existing fields).

Recently, the assets property from the Game and Series structures has been changed to no longer contain width and height properties, constituting a breaking change.

This was only vaguely detailed in last month's site announcement:

Some community tools were unfortunately broken for a short while due to the data migration process changing how some assets were being stored.

As the documentation itself states, this is what you have a versioned API for: to prevent existing tooling from breaking. If the old way the assets were stored would cause issues if it was kept as is, and would require breaking changes to get in working order, implement the changes in a new version branch of the API and deprecate the old version branch.