After talking to some of you at the office on Friday (was great, thanks!), and reading some new suggestions (thanks Brion), it seems API has gained several distinct, slightly overlapping areas of operation.
* SQL-like: This is what the API is best at - providing complex structured access to the database - various page properties and lists like "what pages link to X". The prime beneficiaries are bots (spam fighting, link/iw fixing, etc). Required improvements are fairly cosmetic in nature - minor refactoring, warning/error localization, per module versioning (see
RFC).
* Actions (MasterDB changes): API has greatly grown in this area, providing access to most MW functionality like editing, uploading, watching, account creation, etc. Some cleanup work might still be required, i.e. better token management, but overall this portion is also fairly mature.
* Content - wiki markup/html/sub-sections - this area seems to need improvements the most, due to the much wider variety and style of uses and the potential server load.
For example, mobile requires quick access to rendered individual sections of an article, a web site might embed the page header, a javascript clients might want some pieces of information specific to the given site - text from some table, template parameters, and many other - this list
needs to be expanded for better planning, ideally at the
RFC page.
Unlike query, content-access rarely requires multi-source aggregated results, yet has a much higher usage load, making it the primary target for caching. In my opinion, this difference is the root of misunderstanding between the REST and the current API style advocates.
This brings us to how we want to grow the "content API", assuming that caching is by far the most important concern:
* JSON-only output
* Minimum number of parameters
* URL rewriting