Hi,
we are considering a policy for REST API end point result format
versioning and negotiation. The background and considerations are
spelled out in a task and mw.org page:
https://phabricator.wikimedia.org/T124365https://www.mediawiki.org/wiki/Talk:API_versioning
Based on the discussion so far, have come up with the following
candidate solution:
1) Clearly advise clients to explicitly request the expected mime type
with an Accept header. Support older mime types (with on-the-fly
transformations) until usage has fallen below a very low percentage,
with an explicit sunset announcement.
2) Always return the latest content type if no explicit Accept header
was specified.
We are interested in hearing your thoughts on this.
Once we have reached rough consensus on the way forward, we intend to
apply the newly minted policy to an evolution of the Parsoid HTML
format, which will move the data-mw attribute to a separate metadata
blob.
Gabriel Wicke
Hello,
Just wanted to let you know that I am flying back to Europe today and I am
not going to be working until next Thursday. In case of emergency, I should
be able to respond, though.
Have a nice week-end,
Marko
--
Marko Obrovac, PhD
Senior Services Engineer
Wikimedia Foundation
Hello services-list,
since my very first contact with JSON, I was asking myself: Why can't
people simply use XML?
In the meantime I got aware of the advantages, especially for fast
prototyping and high performance applications.
However, when applications get larger, more complex and more mature
the absence of schema information is problematic.
For example, I found writing the parser for the WikiData dump [1]
quite exhausting. Alternatives like Json-lib work well for testing,
but I was quite worried about stability after hitting a log tail bug
[2]. Moreover, in the PHP Math extension it's often uncomfortable to
figure out which JSON properties are set under certain circumstances
[3]. Yesterday, I discovered another problem related to a missing JSON
schema [4] which finally motivated me to start this effort to discuss
about JSON schema options.
For the communication between services, we use spec files. This is a
great thing. But would it not be even better to use a JSON schema even
within services. So one could throw exceptions right at the place
where the problem occurs. I'm aware that there are approaches for a
JSON schema like [5], but I'm not sure if that is convenient to use in
practice.
To keep the discussion focused, we could use "how HTTP errors are
supposed to look" [6] as a running example to discuss how JSON schema
definition and validation could work.
Best
Physikerwelt
PS: This is my first post the services-list. I hope it fits well to
the idea of this list.
[1] https://github.com/physikerwelt/WikidataListGenerator/blob/master/src/main/…
[2] https://twitter.com/physikerwelt/status/683286844721741824
[3] https://phabricator.wikimedia.org/T119300
[4] https://phabricator.wikimedia.org/T126057
[5] http://jsonschema.net
[6] https://github.com/wikimedia/service-template-node/blob/master/doc/coding.m…