API talk:REST API/Extensions

Here's an example from GrowthExperiments:

• Extension.json registration
• JS call to the endpoint
• REST route handler

I'm struggling with this and neither the documentation nor Extension:Examples seem to cover it.

@Sophivorus Here's an example from GrowthExperiments:

• Extension.json registration
• JS call to the endpoint
• REST route handler

- By default, use REST routes for new API endpoints.

- If you expect a codebase that's already using mostly Action API modules, add one, also.

- If you've got data structures or processes that don't fit well into a RESTful model, try again. If it really won't work, do an Action API module.

Thanks for these docs! I was able to follow them to add an endpoint for an extension (GrowthExperiments). But, I was unsure when we should be defining RestRoutes and when we should use APIModules (which extend ApiBase). Could someone please clarify this?

Hi, @KHarlan (WMF). Great to hear that you were able to add an endpoint! Thanks for asking this question. The Core Platform Team is meeting next week to discuss this, and we'll get back to you with an answer soon.

@APaskulin (WMF) Hi, just checking to see if you all had any further guidance on this? Thanks!

I think @DKinzler (WMF) gave me an answer just before the holidays but I've forgotten what he said by now :)

I don't remember either :) I have asked @EProdromou (WMF) to clarify. From a practical standpoint, I'd do REST if it's a good fit for your use case - that is, if you don't need complex queries, optional output, generator logic, etc.

Here's what I'd say:

- By default, use REST routes for new API endpoints.

- If you expect a codebase that's already using mostly Action API modules, add one, also.

- If you've got data structures or processes that don't fit well into a RESTful model, try again. If it really won't work, do an Action API module.

I hope that helps!

Alex, what do we need to move this from "draft" to "final"?

The RFC was approved yesterday, so we're good to move this forward. I'll need to meet with Bill for ~40 mins, plus some extra time for review. Let me know which sprint we should include that work within, and I'll set up the meeting.

@EProdromou (WMF) This doc has been reviewed and moved out of the draft stage. Feel free to share with other teams and direct any feedback or questions to the discussion page.

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.

Thank you! This is great feedback! I've applied your suggestions and removed the Draft banner from the doc.