This looks very good. I confirmed that the relevant code made it into 1.34 before that branch was separated from master.
A few minor complaints:
1) In the "Handling Requests" section the sentence "run() must be declared in the subclass; it cannot be declared as abstract because it has a variable parameter list." is good information but feels a awkwardly placed.
2) In the "Handling Requests" section, the document says "SimpleHandler provides accessors such as" and goes on to list three accessors. While that is technically true, SimpleHandler only provides those because it inherits those from Handler - .you get those accessors even if you derive from Handler and not SimpleHandler.
Here's my suggestion for reorganizing that section. Of course, you're the writer so feel free to manipulate it as you see fit.
=========
To implement a new handler, you can extend the base Handler class. Handler provides accessors such as:
- getRequest(): Returns the RequestInterface object.
- getConfig(): Returns the RestRoutes configuration object for the current route, decoded from JSON.
- getResponseFactory(): Returns a ResponseFactory object containing a variety of convenient factory functions for creating a response object.
Handler subclasses should implement the execute() function, which is called when the endpoint is invoked. See the generated MediaWiki documentation for accessors available to the base Handler class.
For simpler parameter mapping, extend the SimpleHandler class, which derives from Handler. SimpleHandler unpacks parameters from the path template and passes them as formal parameters to run(). SimpleHandler subclasses should implement run() instead of execute().
See the generated MediaWiki documentation for all accessors available to SimpleHandler.
Here's an example handler for a route that applies a text transformation to the value_to_echo provided in the path.
=========
I omitted everything about "abstract". That's an implementation detail, and if extension developers do it wrong, PHP won't be shy about telling them. :-)
I have not yet followed up with Nikki on the items that we said might be changed and/or added to the Example extension, but I don't think that has to block marking this document as Final.