The action items from the September 11 meeting are:
YDoneI have added Done based on my understanding of the current status, please feel free to edit.
The REST storage service and public content API are now discussed in these two closely related RFCs: Storage service and Content API.
Wikia has released a REST API that covers their immediate needs: . They also have an API team that might work on a more general REST API. I hope that we can collaborate with them on the REST API.
Here is a full copy of the etherpad before it disappears:
API roadmap conversation, Sept 11 2013 at WMF office * Attendees: Yuri, Max, Yuvi, Erik B, Brad, Sumana, Subbu, Gabriel, RobLa, Roan, Federico, Tim == REASONS / JUSTIFICATIONS == Current proposal: https://www.mediawiki.org/wiki/Requests_for_comment/API_roadmap * Change output format - structured warnings / errors, localization ** Kill XML specifically :( (it's 25% of non-OpenSearch traffic but it's a mess and needs to die) * Split traffic between server pools depending on action ** Change URL to e.g. api.php/query?... *** Why make the URL longer? == Discussion == * Module refactoring - https://www.mediawiki.org/wiki/Requests_for_comment/API_roadmap#Modules_refactoring Drawbacks to versioning modules, versus individual flags: * Making promises we can't keep: we say action=foo~3 isn't going to change, but then some security issue or core change comes along and we have to break it anyway. * Code rot: "foo~3" implies an entirely separate module, the code for which will easily rot. ** Yes, the version *could* be treated as a feature flag within the module. Then you have this vaguely-named flag that doesn't indicate what it does besides "version". * Say we make "foo~3", then "foo~4". If a client wants something introduced in ~4, they have to accept ~3 as well. ** Encouraging people to upgrade to the latest version is often a benefit *** But forcing them to upgrade many features for one feature? URL change won't help with caching yet -> REST content API * query param order random, cannot be purged * don't want to wrap HTML in JSON https://www.mediawiki.org/wiki/Talk:Requests_for_comment/API_roadmap#Clean_up_formats_23045 Wikia's requirements: work with SDKs their ecology likes * REST ** What kind of REST? it means something different to everyone! ** Cacheable as much as possible -> no query params, deterministic URL so purgeable ** Representations? State Transformations? *** Content types, not everything should be wrapped in JSON **** +1 ** Discoverability - API results include URL's to possible state transofmrations, related resources, etc. Yuri: How will we proceed in changing the API? * Sumana advises: consult existing API usability research, just as we consult users & MW developers How do we change defaults? Star versus underscore is so JS can do "foo._" instead of "foo['*']" > Avoid underscores in js identifiers per conventions, maybe use "content" instead of "*" / "_" (also more descriptive) Idealist vs Pragmatism - Do you want something beautiful? Or something that continues to work? Why can't it do both? * The argument is to find specific use cases for each individual change, an overall beautiful API is not definable as individual little pieces but as an overarching design methodology ==NEXT== * Wikia makes their RFC public, ASAP :) - Federico ** Separate RfC re RESTful API? ** Prototype Parsoid REST API - Gabriel * Find motivating use case re flags versus versions - Yuri * Restructure current RFC - Brad/Yuri ? * Sumana to post this etherpad onwiki, email mediawiki-api & wikitech-l
