Background
There are three primary problems with the current base URL routing patterns:
- 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}
- The canonical “api” (/w/api.php) pathway is used for the Action API, making preferred REST endpoints harder to discover.
- 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.
- 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