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(a)wikimedia.org> wrote:
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
_______________________________________________
Mobile-l mailing list
Mobile-l(a)lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mobile-l
--
EN Wikipedia user page:
https://en.wikipedia.org/wiki/User:Brian.gerstle
IRC: bgerstle