Page MenuHomePhabricator

Introduce REST entities extensively/upfront to fully represent defined schema in code.
Open, LowPublic

Description

Context

As far as we have defined scheme for REST Api:
https://www.mediawiki.org/wiki/Core_Platform_Team/Initiatives/Core_REST_API_in_MediaWiki/Schema

it would be useful to have that represented in the code as Entities.

Say at the moment SearchHandler outputs results that contain the thumbnail using SearchResultThumbnail, but on the scheme, it's called FileRepresentation. File, according to the scheme should also contain preferred, medium fields of FileRepresentation type.

Though at the moment SearchResultTumbnails belongs to the MediaWiki\Search domain and has nothing common with, REST, in fact, every change in REST/scheme automatically should be reflected in SearchResultTumbnails, especially when adding new fields.

So, the goal is to reduce the mess in naming/modeling and make serialization simpler and more strict.

Expected Result:

  • classes Page, Revision, File, FileRevision, FileRepresentation should be created under MediaWiki\REST\Entities namespace.
  • Serializers that convert those classes into php array or JSON should be added for each fo file.
  • (optionally) REST handlers should return entities rather than formatted JSON.

Event Timeline

I've had a similar idea before in T237692 but I like this proposal better.

Can use these existing schemas as a reference to codify and enforce uniformity among the endpoints

Change 620761 had a related patch set uploaded (by Ppchelko; owner: Ppchelko):
[mediawiki/core@master] Demo: introduce RESTEntity to MW REST framework

https://gerrit.wikimedia.org/r/620761

Change 622430 had a related patch set uploaded (by Ppchelko; owner: Ppchelko):
[mediawiki/core@master] Demo2: RESTEntitySerializers

https://gerrit.wikimedia.org/r/622430

daniel lowered the priority of this task from High to Medium.Oct 12 2020, 3:50 PM
WDoranWMF lowered the priority of this task from Medium to Low.Nov 4 2020, 5:11 PM

Adding missing MediaWiki-REST-API code project tag as Platform Team Initiatives (MW REST API in PHP) team tag is archived and its parent Platform Engineering team does not exist anymore