Talk:Wikimedia Apps/App Services
Add topicMVP & Scope
[edit]Instead of replacing the entire API at once, can't we write a micro service that just replaces, for example, search? I think the scope is already too large, and focusing services on a feature level should facilitate keeping the services small (SOA) and shipping it quickly. BGerstle (WMF) (talk)
API versioning approaches
[edit]Content Type
[edit]RESTBase generally uses MIME type versioning like this:
application/json; profile=mediawiki.org/specs/app_page_bundle/1.0.0
This is spec'd 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 of
- stable any change to stable end points will increment the major API version (/v1/) following semver
URL component
[edit]For example /v1/resource/... versus /v2/resource/....