Page MenuHomePhabricator

Improve developer guidelines and documentation for MW REST API framework
Open, LowPublic

Description

In T252390 I tried to implement a new MW REST API endpoint. While I liked the initial documentation especially the SimpleHandler, but it was a bit too simple for my application. However, it took most of the Hackathon Weekend to read the code and the unit tests to understand how the request handling works.

It would be good to provide more advice on how to do

  • testing and
  • documentation.

Especially for people coming from RESTbase one is used to do both at the same time with swagger examples.

I would have hoped for some boilerplate code to generate test like testCheckPreconditionsSinX in https://gerrit.wikimedia.org/r/#/c/mediawiki/extensions/Math/+/595558/3/tests/phpunit/Math/Rest/CheckTest.php would allow for data-driven rest endpoint checks.
Especially it took quite long to figure out that a Router requires having a non-empty list of wiring files.

Event Timeline

Physikerwelt created this task.
eprodromou added a subscriber: eprodromou.

Alex, I don't know if you saw this. It's an interesting bit of feedback! Let's discuss at our next 1-on-1.

apaskulin added a subscriber: apaskulin.

Yes, I saw this. It's great feedback! I hope to be able to work on this in the future, but since I don't have the availability now, I'm unassigning myself so it doesn't block someone else from picking it up.