We need a plan regarding the outlook and extension of our public API hierarchy.
== Current Status ==
Thus far, RESTBase has been exposing only the API pertaining to pages retrieved from Parsoid, their transforms and information about revisions fetched from the MW API. With the latest addition of end-points proxying requests to Graphoid, a domain's `v1` root tree looks like this:
```
/{domain}/v1
-- /page
-- /revision
-- /title
-- /namespace
-- /html
-- /data-parsoid
-- /graph
-- /transform
```
Most of the endpoints are grouped under `/page` because, in one way or another, they relate to a page or an aspect of it; all but `/revision` require the client to supply the page title. Another aspect to note is that currently page formats (`/html`) are mixed with types (such as `/graph`).
== New Endpoints ==
The API needs to evolve because we want/need to:
- expose more endpoints mapping to MW API calls to increase the comprehensiveness of the provided endpoints
- proxy new services and ultimately remove the Parsoid caches
The next services we want to proxy include Mathoid, Citoid, the MobileApps service and Revscoring.
=== MobileApps ===
The aim of the MobileApps service is to provide page content massaged for the needs of (native) mobile readers. It it able to generate two types: the full-blown version targeted at newer, more powerful mobile devices, and a lite version targeting older and slower devices. Since it deals directly with page content, it seems logical to put its endpoints under `/page`:
```
/{domain}/v1
-- /page
-- /mobile-json-lite/{title}
-- /mobile-json-full/{title}
-- /mobile-json-lead/{title}
-- /mobile-json-remainder/{title}
```
=== Revscoring ===
Likewise, //revscoring// is about classifying revisions, and is, thus, tied to a particular revision. Hence, it is natural to place it under `/page/revision`:
```
/{domain}/v1
-- /page/revision/{revision}
-- /score/
-- /score/wp10
-- /score/reverted
```
Notes:
- `/score/` would give a listing of available scoring methods, while the other would yield their respective results for a given revision.
- The service itself supports revision batching - supplying multiple revisions for which to get the score. This is currently not covered by these API endpoints.
=== Mathoid ===
Math endpoints have no particular relation to the page where mathematical symbols and elements are included, so it can be moved into a separate sub-tree:
```
/{domain}/v1
-- /media
-- /math
-- /{format}/{query}
```
The rationale for `media` here is that Mathoid emits media representations (images) of mathematical formulae. `query` contains the textual representation of the formula to render. While it can be comprehensive, thus making the URL long, in practice browsers and servers support at least 2K-long URLs, which is sufficient in this case.
=== Citoid ===
In the same vein as Mathoid, Citoid's output does not depend on the page on which the citation is displayed:
```
/{domain}/v1
-- /data
-- /citation
-- /{format}/{query}
```
=== Other Services ===
These examples establish a satisfactory root hierarchy:
```
/{domain}/v1
-- /page
-- /transform
-- /media
-- /data
```
Using such an outline, it is rather easy to place new services, such as Hierator or Wikidata:
```
/{domain}/v1
-- /media
-- /hieroglyph
-- /thumb
-- /data
-- /wikidata
```