On Thu, Feb 5, 2015 at 12:04 PM, Brion Vibber <bvibber(a)wikimedia.org> wrote:
> - Versioning? What if we add or remove a field from the response? We
> should version this. Can we do this easily?
>
>
In RESTBase we generally use mime type versioning like this:
application/json;
profile=mediawiki.org/specs/app_page_bundle/1.0.0
This is specced in the Swagger spec & enforced by RESTBase. On version
mismatch from stored content, the backend service is called to re-generate
or upgrade the content, which is then saved back. It can be passed the
stored content to make re-generation more efficient.
If needed, clients could also signal the content-type they expect with an
accept header. The details of how things would then be upgraded /
downgraded would need to be worked out in case you really need this. In
general, you can go a long way by only adding properties while remaining
backwards-compatible with the old properties.
We also distinguish stability per end point:
- *experimental *end points can change at any time (effectively private,
use at your own risk)
- *unstable *end points can change, but we make an effort to avoid
breakage and notify users
- any change to *stable* end points will increment the major API version
(/v1/) following semver
The mobile API should probably be marked as experimental, as it is
primarily intended as an API for apps we control.
Gabriel