Page MenuHomePhabricator

Epic: REST API vNext Beta Module > Canonical Routing (PP3.5.2 26/27)
Open, Needs TriagePublic

Description

Background

There are three primary problems with the current base URL routing patterns:

  1. Three different routing patterns are used for REST endpoints: https://{project}/w/rest.php/vX/{endpoint}, https://{project}/api/rest_v1/{endpoint}, and https://api.wikimedia.org/core/v1/{project}/{language}/{endpoint}
  2. The canonical “api” (/w/api.php) pathway is used for the Action API, making preferred REST endpoints harder to discover.
  3. Implementation details leak into public URLs (via /w/rest.php), yet are not even necessarily accurate, given that some endpoints no longer share the underlying php infrastructure.
  4. Many endpoints share a single version prefix that ties unrelated endpoints together, meaning any breaking change to a given endpoint forces a version bump across the board.

A canonical routing pattern (eg: /api/{moduleName}/vX/) hides implementation details and scopes versioning to individual modules, so changes to search don't affect content endpoints, and moving an implementation from PHP to another technology is invisible to callers. Additionally, simplifying the core URL to /api/ allows us to eventually present blended API modules, where we will blend REST and Action/RPC infrastructure for related capabilities.

Scope

  • A new canonical base URL for all vNext APIs is established. ({project]/api/*)
  • The ‘baseUrl’ is updated for all new and existing endpoints under the following patterns are rerouted to follow the new pattern:
    • Rest.php
    • Api.php --> Action API will remain unaffected
  • New endpoints automatically have a redirect put in place if requests are made to *.php routes.
  • Announcement content:
    • The current /api/ landing page will disappear (ie: https://en.wikipedia.org/api/)
    • New routing pattern is available; existing traffic will be rerouted through the new endpoint structure
  • New processes
    • How endpoints redirects will be communicated and what developers need to respond to redirect responses

Out of scope
The following API families are out of scope for now, and will continue to follow their standard pathing patterns since they do have the same pathing expectations in general and are managed outside of MediaWiki:

  • api/rest_v1 → This API already superficially follows the desired pattern.
  • api.wikimedia.org
  • query.wikidata.org
  • commons-query.wikimedia.org
  • stream.wikimedia.org

Event Timeline

Change #1328574 had a related patch set uploaded (by Daniel Kinzler; author: Daniel Kinzler):

[mediawiki/core@master] REST: make ModuleManager use RestPath

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

Change #1328574 merged by jenkins-bot:

[mediawiki/core@master] REST: make ModuleManager use RestPath

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

Change #1338909 had a related patch set uploaded (by Daniel Kinzler; author: Daniel Kinzler):

[mediawiki/core@master] REST: Add a PageHandler with suppor for props

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

Change #1342175 had a related patch set uploaded (by Daniel Kinzler; author: Daniel Kinzler):

[mediawiki/core@master] REST: Strengthen page redirect and access test coverage

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

Change #1342176 had a related patch set uploaded (by Daniel Kinzler; author: Daniel Kinzler):

[mediawiki/core@master] REST: Refactor RevisionSourceHandler into RevisionHandler

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

Change #1342175 merged by jenkins-bot:

[mediawiki/core@master] REST: Preserve path parameters in redirects

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

Change #1338909 merged by jenkins-bot:

[mediawiki/core@master] REST: Refactor PageSourceHandler into PageHandler

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

Change #1342176 merged by jenkins-bot:

[mediawiki/core@master] REST: Refactor RevisionSourceHandler into RevisionHandler

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

I just saw this in tech news so I'm a little behind, what is the plan for MediaWiki to support endpoints with /api/? It was annoying in writing bot code that we needed to have different code for restbase and rest.php and just as we consolidated on the latter that works across all MediaWiki installs it seems like the plan is to now use something that may not work out of the box without extra work.

Implementation details leak into public URLs (via /w/rest.php), yet are not even necessarily accurate, given that some endpoints no longer share the underlying php infrastructure.

How much do end users actually care about the implementation details? I think being able to work out of the box in MediaWiki on most hosts and keeping it the same everywhere is better than requiring extra webserver customization and more paths/special cases for client libraries and bot frameworks.

The canonical “api” (/w/api.php) pathway is used for the Action API, making preferred REST endpoints harder to discover.

Since we're already planning to change a lot ... why not just fix/change this? Why not turn api.php into a single landing page for all the APIs instead of just the Action API? TBH the invocation patterns of rest.php and api.php are totally different (url paths vs query paramters) that you could combine the two and it would probably just work?