Mark and announce transform endpoints with trailing slash as deprecated
Closed, ResolvedPublic
Actions

Assigned To

Authored By

	HCoplin-WMF
	Sep 17 2025, 12:59 PM

Description

We currently have two versions of every transform endpoint, surfaced both through the Sandbox documentation and actual functionality. One version of the endpoint allows for a trailing slash without additional information, whereas the other version only accepts a trailing slash if it is followed by a page title (see screenshot below). This is confusing for users, presents an anti-pattern for REST principles, and is needlessly complicated for us to support.

Additionally, the current trailing slash endpoint sees limited traffic with a high rate of errors and test calls. It would be best to deprecate and fully remove it from our system before we see additional adoption. The work outlined in this ticket focuses on the deprecation announcement and formally marking the trailing slash endpoints as deprecated, with a follow up ticket to actually remove them from code.

Conditions of acceptance

Send deprecation announcement to wikitech-l
Send deprecation announcement to WikiTech News
Mark endpoints as deprecated in documentation
Surface deprecation status within the REST Sandbox description --> Add deprecated: true to the OpenAPI spec
Create and update changelog (pending sign off on changelog style guide proposal & location alignment)

NOTE: A future/follow up task will actually remove them from code.

Details

Related Changes in Gerrit:

	Subject	Repo	Branch	Lines +/-
	Add deprecated "since" date to already-deprecated transform endpoints.	mediawiki/core	master	+18 -6
	Deprecate transform endpoints with trailing slashes.	mediawiki/core	master	+13 -6

Customize query in gerrit

Related Objects
Search...

		Status	Subtype	Assigned	Task
		Resolved	BUG REPORT	BPirkle	T391712 Transform "Try it out" doesn't work in REST Sandbox
		Resolved		HCoplin-WMF	T404854 Mark and announce transform endpoints with trailing slash as deprecated

Event Timeline

HCoplin-WMF created this task.Sep 17 2025, 12:59 PM

HCoplin-WMF updated the task description. (Show Details)

HCoplin-WMF mentioned this in T404855: [Jan 2026] Remove trailing slash routes for Transform endpoints.Sep 17 2025, 1:04 PM

HCoplin-WMF moved this task from MWI-Sprint-18 (2025-09-09 to 2025-09-23) to Next Up on the MW-Interfaces-Team board.Sep 17 2025, 1:17 PM

HCoplin-WMF edited projects, added MW-Interfaces-Team; removed MW-Interfaces-Team (MWI-Sprint-18 (2025-09-09 to 2025-09-23)).

There is some background discussion on the trailing slashes in T392608: [SPIKE] Determine the best approach for surfacing 'Transform' endpoints in the REST Sandbox. Summary is that this is more of an accident of how the original versions where coded, than an intentional decision.

I'm very much in favor of eliminating the "trailing slash" versions.

HCoplin-WMF updated the task description. (Show Details)Sep 18 2025, 7:32 PM

HCoplin-WMF mentioned this in T405038: [SPIKE] Propose an in-code mechanism for marking endpoints as deprecated.Sep 18 2025, 8:18 PM

HCoplin-WMF updated the task description. (Show Details)Sep 24 2025, 11:22 AM

Change #1193295 had a related patch set uploaded (by BPirkle; author: BPirkle):

[mediawiki/core@master] Deprecate transform endpoints with trailing slashes.

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

gerritbot added a project: Patch-For-Review.Oct 3 2025, 3:34 AM

Change #1193295 merged by jenkins-bot:

[mediawiki/core@master] Deprecate transform endpoints with trailing slashes.

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

ReleaseTaggerBot added a project: MW-1.45-notes (1.45.0-wmf.22; 2025-10-07).Oct 6 2025, 10:00 PM

Maintenance_bot removed a project: Patch-For-Review.Oct 6 2025, 10:30 PM

This change to mark these endpoints as deprecated in the OpenAPI spec is riding this week's train.

They will not immediately begin sending the Deprecation header, but support for that is riding this week's train and we can add that in a followup.

Change #1194729 had a related patch set uploaded (by BPirkle; author: BPirkle):

[mediawiki/core@master] Add deprecated "since" date to already-deprecated transform endpoints. These endpoints were marked as deprecated in 1.45.0-wmf.22, but no deprecated "since" date was included. Add that, so that the RFC9745 "deprecation" header will be sent with responses.

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

gerritbot added a project: Patch-For-Review.Oct 8 2025, 8:07 PM

Change #1194729 merged by jenkins-bot:

[mediawiki/core@master] Add deprecated "since" date to already-deprecated transform endpoints.

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

Maintenance_bot removed a project: Patch-For-Review.Oct 9 2025, 1:30 AM

ReleaseTaggerBot edited projects, added MW-1.45-notes (1.45.0-wmf.23; 2025-10-14); removed MW-1.45-notes (1.45.0-wmf.22; 2025-10-07).Oct 9 2025, 2:00 AM

BPirkle mentioned this in T391712: Transform "Try it out" doesn't work in REST Sandbox.Oct 21 2025, 11:02 PM

BPirkle moved this task from Next Up to MWI-Sprint-21 (2025-10-21 to 2025-11-04) on the MW-Interfaces-Team board.Oct 22 2025, 12:16 AM

BPirkle edited projects, added MW-Interfaces-Team (MWI-Sprint-21 (2025-10-21 to 2025-11-04)); removed MW-Interfaces-Team.

HCoplin-WMF updated the task description. (Show Details)Oct 27 2025, 2:18 PM

Marking this as resolved. Sunsetting will occur at the end of Jan 2026 (called out in all relevant comms).