API talk:REST API/Extensions

Draft -> Final

Alex, what do we need to move this from "draft" to "final"? EProdromou (WMF) (talk) 20:10, 23 October 2019 (UTC) Reply

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. APaskulin (WMF) (talk) 15:47, 24 October 2019 (UTC) Reply

@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. APaskulin (WMF) (talk) 17:52, 20 November 2019 (UTC) Reply

Comments on draft

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. BPirkle (WMF) (talk) 04:36, 20 November 2019 (UTC) Reply

Thank you! This is great feedback! I've applied your suggestions and removed the Draft banner from the doc. APaskulin (WMF) (talk) 17:48, 20 November 2019 (UTC) Reply

When to use instead of APIModules?

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? KHarlan (WMF) (talk) 21:46, 3 December 2019 (UTC) Reply

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) (talk) 17:59, 5 December 2019 (UTC) Reply

@APaskulin (WMF) Hi, just checking to see if you all had any further guidance on this? Thanks! KHarlan (WMF) (talk) 11:05, 3 January 2020 (UTC) Reply

I think @DKinzler (WMF) gave me an answer just before the holidays but I've forgotten what he said by now :) KHarlan (WMF) (talk) 11:06, 3 January 2020 (UTC) Reply

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. DKinzler (WMF) (talk) 12:51, 3 January 2020 (UTC) Reply

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! EProdromou (WMF) (talk) 18:41, 6 January 2020 (UTC) Reply

How to do a POST request?

I'm struggling with this and neither the documentation nor Extension:Examples seem to cover it. Sophivorus (talk) 16:00, 31 August 2022 (UTC) Reply

@Sophivorus Here's an example from GrowthExperiments:

• Extension.json registration
• JS call to the endpoint
• REST route handler KHarlan (WMF) (talk) 10:16, 2 September 2022 (UTC) Reply