Page MenuHomePhabricator

Closed, ResolvedPublic


A component that does the following:

  • Maintains a routing table that maps a URI Template to a route handler
  • Tests incoming REST API requests against the routing table to determine which route handler should handle the request
  • Executes the route handler
  • Returns results of the route handler to the client

The router should manage common REST API functionality, to avoid repetition in each handler. This should include:

  • Handling HTTP caching headers (If-Modified-Since, If-None-Match)
  • Authentication

Event Timeline

One question I have about routing is how it will be implemented. I see at least 3 options for implementation:

  • New entry point (e.g. rest.php?path=/page/html/Cheese). This is how the Action API works (api.php)
  • Special page (e.g. Special:Rest/page/html/Cheese)
  • New action argument for index.php (e.g. action=rest&path=/page/html/Cheese)
  • New action argument for api.php (action=rest&path=/page/html/Cheese)
  • Some other method

I don't think any of these implementations would prevent using Varnish or another mechanism to make "pretty URLs" for API paths.

I would lean towards option 1, rest.php. Special pages are mostly for UIs, not APIs. Actions usually have a required title parameter and are intended for taking an action on a page.

We definitely want a new entry point for this, everything else has unnecessary overhead. That raises some issues though:

  • How do we handle it in the Wikimedia heterogenous deploy environment? (Seems pretty straightforward, just needs to be done.)
  • Obviously we want nice URLs where the entry point is hidden and handled in some network layer config (much like index.php in the /wiki/... requests). Also needs to be done, but more importantly, how do we handle it in third-party MediaWiki installs? Presumably we want a MediaWiki install to work out of the box, without any webserver configuration. Should there be some way for clients to autodetect the API base URL? Can we assume that something like /w/rest.php/page/html/Foo works, or do we need to support /w/rest.php?path=/page/html/Foo (which comes with all kinds of complications, like different escaping rules or different way of attaching query parameters, so we aren't really talking about a base URL at this point)? Should the MediaWiki installer provide some kind of support / feature detection?

Probably worth its own task.

Wrt routing, probably worth looking at other frameworks and see what features they support and whether we find those interesting. I'm thinking of things like middleware, nested routers, rerouting, flexible parameter validators...
Also this is probably the layer where we'll end up doing things like CORS and some level of content negotiation, we should take stock of the things the action API does that will be needed here as well.

Also, how will dependency injection work, given that we probably don't want to force authors to write a handler factory for every handler (or do we?) but need to be able to lazy-load dependencies? We decided to avoid markup-based dpeendency injection in MediaWiki, but this is one area where we might want to reconsider.

I suggest merging this task with T221177. The same things are being discussed in both places.

eprodromou added a subscriber: eprodromou.

This is done, for now.