I forgot to fill in my "*" next to "app services."  The name is not a great one, and I'm open to suggestions that are more specific or intuitive.

On Thu, Feb 5, 2015 at 4:04 PM, Brian Gerstle <bgerstle@wikimedia.org> wrote:
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*.  There's even a discussion page 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:


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




--
EN Wikipedia user page: https://en.wikipedia.org/wiki/User:Brian.gerstle
IRC: bgerstle



--
EN Wikipedia user page: https://en.wikipedia.org/wiki/User:Brian.gerstle
IRC: bgerstle