Single page app + frequently changing REST API - deployment - a lot of API versions OR no deletion and renaming

Question

Overview:

We have a rails REST API app that's gonna be published soon together with client app (single page app written in JS) . We intent to deploy new stuff on almost daily basis. For now the API is only used by us internally.

Questions:

• How to manage deployment because we deploy each app separately?
• Should we always deploy them together? Should we raise API version for each deployed change?
• How to reload JS app when new version of API is available?
• Should we not change the API version but keep backwards compatibility in mind? So only add new keys in JSON responses, no renaming, no deletions, no changing of URLs, ...

Are there any best practices described somewhere about this particular problem?

Answer 1

It is considered a best practice to only version a RESTful API when making a breaking change.

I would strongly suggest not releasing the API to the public until it has stabilized more. As long as it is internal-facing only, the frequent changes won't be as big of a deal. Once your API goes public, you'll want to limit the number of breaking changes (new versions) as much as possible, so work with your best customers before your public release to make sure the API is adequate, and try to design it with backwards compatibility in mind.

You should only need to pair the releases if there's a breaking change on the API side. Pairing them or not may be a business decision ("It's easier for our customers to have one version number to worry about than two").

You might also consider resetting the version number at release time so that the public is given the stable API at version 1 instead of 18.