User:GWicke/Notes/MW service URI layout considerations

Deterministic URIs for caching
Deterministic URIs let us cache and purge cached requests. REST-style paths are generally deterministic, but using them also for page-related sub-resources is complicated by literal slashes in page names and public URIs. We can instead use a query string to mark up the sub-resource. The easiest method to make those deterministic is to use only a single key-value pair, so that ordering of query parameters cannot introduce non-determinism.

Options for sub-resource encoding in query strings considered are:
 * : Sounds odd, as the key does not really match the sub-resource on the right.
 * : Would require query string key order normalization (alphabetic ordering) in caches as many client libraries don't let users control the order of parameters. Requests with missing mandatory parameters or invalid combinations are rejected. Unclear how listings would be modeled in a pure key-value model. With paths those naturally fall out of incomplete paths and the trailing slash. Harder to discover valid parameter combinations; with a path any path prefix is valid.
 * : Looks more path-y, but is longer and more noisy.
 * : Short and does not induce strange meaning like key=value. The path is a bit more broken up than the second option, but looks natural and less noisy for people used to query strings. Current favorite.

API entry points
We have both page-related resources (revisions, metadata) and page-independent resources. Both can be handled by a generic entry point.

Options:
 * separate entry point
 * - does not work well for wikis without a  style prefix.
 * - does not work well for wikis without a  style prefix.


 * Stay within the wiki namespace, but don't collide with articles as those can't start with an underscore or colon.
 * + Works well with or without  style prefix.
 * (-) /wiki/_api is currently redirected to /wiki/Api, so could potentially break some incoming links. Unlikely to matter in practice.
 * (-) leading underscore has 'private' connotation
 * (-) _api prefix won't be used in other ways to access the API, so less consistent
 * (-) _api prefix won't be used in other ways to access the API, so less consistent


 * + very compact
 * + can be used consistently internally (in the PHP virtual REST service interface) and externally
 * (+) currently an invalid title, so won't break existing incoming links
 * (+) consistent with use of colons in wiki links and namespaces
 * - possibly slightly more cryptic than
 * This is my current favorite.
 * This is my current favorite.

For page-related sub-resources like revisions or page metadata we could additionally provide an entry point that reuses the established page URIs as a base (example: . The general disadvantage of having an additional entry point for the same content is consistency and more potential for confusion. An option would be to treat the global API entry point as the canonical version, and only redirect there from the page-related 'convenience' entry point. It is not clear that the small convenience is worth it though.

Options:
 * + consistent with global API
 * - not versioned
 * - not versioned


 * + also versioned
 * - inconsistent with global API
 * - inconsistent with global API