In an effort to avoid yet another mega thread, I went ahead and created a Wiki page under the apps space which holds the problems & requirements for app services https://www.mediawiki.org/wiki/Wikimedia_Apps/App_Services*. There's even a discussion page https://www.mediawiki.org/wiki/Talk:Wikimedia_Apps/App_Services where I've cherry-picked Brion & Gabriel's comments, organized by topic. I hope this proves useful and will give us something to go on in the future. I've put my comments so far on the talk page.
On Thu, Feb 5, 2015 at 3:15 PM, Gabriel Wicke gwicke@wikimedia.org wrote:
On Thu, Feb 5, 2015 at 12:04 PM, Brion Vibber bvibber@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
Mobile-l mailing list Mobile-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mobile-l