Summary: certain Reading Lists endpoints currently handled by RESTbase should be rerouted to equivalent MediaWiki REST endpoints. This will unblock this portion of RESTbase sunset. Rerouting is necessary (as opposed to switching callers immediately) because the primary (and perhaps only) callers are WMF mobile apps installed on end user devices, and it will take some time to transition all app users to new app versions that support new paths. See T336693: Re-implement reading lists REST interface outside RESTBase and T348493: Reading List REST Interface: reroute calls for more info.
Mapping of production URLs to be routed to MediaWiki-REST-API endpoints implemented in the Reading Lists extension:
- Setup lists (for the logged-in user)
- HTTP Verb: POST
- Production Endpoint:
- <domain>/api/rest_v1/data/lists/setup
- Example: https://en.wikimedia.org/api/rest_v1/data/lists/setup
- MW REST Endpoint:
- <domain>/w/rest.php/readinglists/v0/lists/setup
- Example: https://en.wikimedia.org/w/rest.php/readinglists/v0/lists/setup
- Teardown lists (for the logged-in user)
- HTTP Verb: POST
- Production Endpoint:
- <domain>/api/rest_v1/data/lists/teardown
- Example: https://en.wikimedia.org/api/rest_v1/data/lists/teardown
- MW REST Endpoint:
- <domain>/w/rest.php/readinglists/v0/lists/teardown
- Example: https://en.wikimedia.org/w/rest.php/readinglists/v0/lists/teardown
- Get all lists (for the logged-in user)
- HTTP Verb: GET
- Production Endpoint:
- <domain>/api/rest_v1/data/lists/
- Example: https://en.wikimedia.org/api/rest_v1/data/lists/
- MW REST Endpoint:
- <domain>/w/rest.php/readinglists/v0/lists/
- Example: https://en.wikimedia.org/w/rest.php/readinglists/v0/lists/
- Create a new list (for the logged-in user)
- HTTP Verb: POST
- Production Endpoint:
- <domain>/api/rest_v1/data/lists/
- Example: https://en.wikimedia.org/api/rest_v1/data/lists/
- MW REST Endpoint:
- <domain>/w/rest.php/readinglists/v0/lists/
- Example: https://en.wikimedia.org/w/rest.php/readinglists/v0/lists/
- Update a list (belonging to the logged-in user)
- HTTP Verb: PUT
- Production Endpoint:
- <domain>/api/rest_v1/data/lists/{id}
- Example: https://en.wikimedia.org/api/rest_v1/data/lists/42
- MW REST Endpoint:
- <domain>/w/rest.php/readinglists/v0/lists/{id}
- Example: https://en.wikimedia.org/w/rest.php/readinglists/v0/lists/42
- Delete a list (belonging to the logged-in user)
- HTTP Verb: DELETE
- Production Endpoint:
- <domain>/api/rest_v1/data/lists/{id}
- Example: https://en.wikimedia.org/api/rest_v1/data/lists/42
- MW REST Endpoint:
- <domain>/w/rest.php/readinglists/v0/lists/{id}
- Example: https://en.wikimedia.org/w/rest.php/readinglists/v0/lists/42
- Create multiple new lists (for the logged-in user)
- HTTP Verb: POST
- Production Endpoint:
- <domain>/api/rest_v1/data/lists/batch
- Example: https://en.wikimedia.org/api/rest_v1/data/lists/batch
- MW REST Endpoint:
- <domain>/w/rest.php/readinglists/v0/lists/batch
- Example: https://en.wikimedia.org/w/rest.php/readinglists/v0/lists/batch
- Get all entries for the given list (belonging to the logged-in user)
- HTTP Verb: GET
- Production Endpoint:
- <domain>/api/rest_v1/data/lists/{id}/entries/
- Example: https://en.wikimedia.org/api/rest_v1/data/lists/42/entries/
- MW REST Endpoint:
- <domain>/w/rest.php/readinglists/v0/lists/{id}/entries/
- Example: https://en.wikimedia.org/w/rest.php/readinglists/v0/lists/42/entries/
- Add a new list entry (to a list belonging to the logged-in user)
- HTTP Verb: POST
- Production Endpoint:
- <domain>/api/rest_v1/data/lists/{id}/entries/
- Example: https://en.wikimedia.org/api/rest_v1/data/lists/42/entries/
- MW REST Endpoint:
- <domain>/w/rest.php/readinglists/v0/lists/{id}/entries/
- Example: https://en.wikimedia.org/w/rest.php/readinglists/v0/lists/42/entries/
- Deletes a list entry (from a list belonging to the logged-in user)
- HTTP Verb: DELETE
- Production Endpoint:
- <domain>/api/rest_v1/data/lists/{id}/entries/{entry_id}
- Example: https://en.wikimedia.org/api/rest_v1/data/lists/42/entries/64
- MW REST Endpoint:
- <domain>/w/rest.php/readinglists/v0/lists/{id}/entries/{entry_id}
- Example: https://en.wikimedia.org/w/rest.php/readinglists/v0/lists/42/entries/64
- Add multiple new entries (to a list belonging to the logged-in user)
- HTTP Verb: POST
- Production Endpoint:
- <domain>/api/rest_v1/data/lists/{id}/entries/batch
- Example: https://en.wikimedia.org/api/rest_v1/data/lists/42/entries/batch
- MW REST Endpoint:
- <domain>/w/rest.php/readinglists/v0/lists/{id}/entries/batch
- Example: https://en.wikimedia.org/w/rest.php/readinglists/v0/lists/42/entries/batch
- Get lists belonging to the logged-in user which contain a given page
- HTTP Verb: GET
- Production Endpoint:
- <domain>/api/rest_v1/data/lists/pages/{project}/{title}
- Example: https://en.wikimedia.org/api/rest_v1/data/lists/https%3A%2F%2Fen.wikipedia.org/Barack_Obama
- MW REST Endpoint:
- <domain>/w/rest.php/readinglists/v0/lists/{project}/{title}
- Example: https://en.wikimedia.org/w/rest.php/readinglists/v0/lists/https%3A%2F%2Fen.wikipedia.org/Barack_Obama
- Get lists recent changes to the logged in users's lists
- HTTP Verb: GET
- Production Endpoint:
- <domain>/api/rest_v1/data/lists/changes/since/{date}
- Example: https://en.wikimedia.org/api/rest_v1/data/lists/changes/since/2024-01-01T00%3A00%3A00Z
- MW REST Endpoint:
- <domain>/w/rest.php/readinglists/v0/lists/changes/since/{date}
- Example: https://en.wikimedia.org/w/rest.php/readinglists/v0/lists/changes/since/2024-01-01T00%3A00%3A00Z
Additional Info
- An interactive sandbox for the existing endpoints is here: https://en.wikipedia.org/api/rest_v1/#/Reading%20lists
- An OpenAPI spec is here: https://en.wikipedia.org/api/rest_v1/?spec (search for tag "Reading Lists")
- All POST/PUT/DELETE operations may include a "csrf_token" query parameter. The new endpoints also allow this to be passed in the body as "token", so callers may transition to that. But at least initially, expect csrf_token query parameters to be present.
- Example query parameters and bodies not provided for endpoints that consume them. If that's needed information, we can provide it. (Or see the above linked sandbox/spec)
TIMING NOTES
If possible, let's schedule the initial switch for the week of April 14, starting with testwiki ONLY for ~2 weeks to support manual testing
Iterative rollout to additional wikis tentatively starting week of April 28. We will provide the desired rollout list and timing soon.
Additional Configuration:
All forwarded calls should include a x-restbase-compat header with a value of 'true'. This instructs the MW REST endpoints to return RESTbase-compatible data.
Acceptance Criteria
- This list is reviewed and approved by @MSantos and @HCoplin-WMF
- This list is reviewed and approved by ServiceOps
- Endpoints are routed through REST Gateway
- Monitoring and testing indicate success