search

AdamVig / GoCoApi

API Server for the GoCoStudent app.
https://gocostudent.adamvig.com/api
GNU General Public License v3.0
0 stars 0 forks source link

Add true API versioning #6

Closed AdamVig closed 8 years ago

AdamVig commented 8 years ago

Currently, each request is sent to /api/[app version], which is helpful but somewhat backwards. Instead, the app should send requests to /api/ with the Accept-Version header, then the API version can be changed and the app will never know the difference.

Restify supports versioned routes out of the box.

API versioning on the request-level should go hand-in-hand with API versioning on the release level, meaning that this project should get on a release schedule using semantic versioning.

AdamVig commented 8 years ago

Restify uses node-semver to interpret the version specified in the Accept-Version header of requests. That means the app can specify Accept-Version: 1.x.x in all requests and receive all bugfixes and minor updates without the possibility of API changes breaking the app.

This will require careful testing in the API development process to identify non-backwards compatible changes and denote them as such by incrementing to the next major version and updating the route definition with the versions it supports (as shown in the Restify docs).

AdamVig commented 8 years ago

The above pull request should have added support for endpoints that supply different data for different versions, but there is no current test case for that scenario so I am deferring until such a time.