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 <http://www.mediawiki.org/wiki/Requests_for_comment/API_Future>).
* 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<http://www.mediawiki.org/wiki/Requests_for_comment/API_Future>
.
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
Most improvements for querying and actions are listed at
http://www.mediawiki.org/wiki/Requests_for_comment/API_Future and are
currently being worked on, but the content approach needs use cases,
requests, and interface suggestions.