stockpile-co / api

The API for Stockpile, an app that manages stuff for organizations.
0 stars 1 forks source link

Add version to endpoints #290

Closed AdamVig closed 7 years ago

AdamVig commented 7 years ago

As a Stockpile developer, I want to release breaking changes to the API in a backwards-compatible way so that I can develop new features without breaking the app.

Depends on app/#339.

AdamVig commented 7 years ago

The implementation is a bit different than expected. Restify is already setting the default version for all routes to the API version specified in package.json, so no major changes have to be made.

When versioning an endpoint, do the following steps:

  1. Duplicate the endpoint in question.
  2. On the old endpoint, add a version property and set it equal to the current version of the API, e.g. version: '1.0.0'.
  3. On the old endpoint, change the name property to include the version, e.g. get all users v1. The name of each version of each endpoint must be unique.
  4. On the old endpoint, rename its handler to include the version it targets.
  5. On the new endpoint, add a new handler that includes whatever breaking change is going to be made.

The new endpoint does not need a version property. It will use the incremented version in package.json.

AdamVig commented 7 years ago

I decided to not implement apiDoc's @apiVersion tag yet. It wants the tag to be present on every documentation block, which seems like a huge maintenance burden when the version is incremented.

I could use a central documentation block that others inherit from so that there is only one place to be updated, but that would require a bit of refactoring.

I'll implement this the first time a route must be versioned.