Thread:Talk:Requests for comment/API roadmap/Follow-up action items meeting september 11/reply (2)

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