Page MenuHomePhabricator
Create Task
Maniphest T388528

Add translatable OpenAPI endpoint descriptions for all remaining endpoints
Closed, ResolvedPublic3 Estimated Story Points
Actions

Description

Description

Endpoint descriptions are helpful for getting basic information about an endpoint's purpose. Including endpoint descriptions also creates a more complete and consistent experience with other modern APIs, as well as other SwaggerUI implementations from across the foundation.

Conditions of acceptance

Following the approach outlined in the related research spike, add translatable endpoint descriptions to all content endpoints:

  • GET /page/{title}/history
  • GET /page/{title}/history/counts/{type}
  • GET /revision/{from}/compare/{to}
  • GET /search
  • GET /search/page
  • GET /search/title
  • GET /page/{title}/links/language
  • GET /page/{title}/links/media
  • GET /file/{title}
  • POST /transform/wikitext/to/html/
  • POST /transform/html/to/wikitext/
  • POST /transform/wikitext/to/html/{title}
  • POST /transform/html/to/wikitext/{title}
  • POST /transform/wikitext/to/html/{title}/{revision}
  • POST /transform/html/to/wikitext/{title}/{revision}
  • For the endpoint descriptions themselves, use the descriptions currently available in the API Portal.
    • If there are endpoints that are missing descriptions in the portal, consult with Halley for generating a new description.
  • All descriptions are translatable by translatewiki.

Details

Related Changes in Gerrit:
SubjectRepoBranchLines +/-
REST: Add translatable OpenAPI endpoint descriptions for all remaining endpointsmediawiki/coremaster+92 -17
Customize query in gerrit

Related Objects
Search...

Event Timeline

HCoplin-WMF created this task.Mar 11 2025, 1:17 PM
HCoplin-WMF moved this task from Incoming (Needs Triage) to Next Up on the MW-Interfaces-Team board.Mar 11 2025, 1:25 PM
HCoplin-WMF triaged this task as Medium priority.Mar 11 2025, 2:49 PM
HCoplin-WMF edited projects, added MW-Interfaces-Team (MWI-Sprint-5 (2025-03-11 to 2025-03-25)); removed MW-Interfaces-Team.
HCoplin-WMF set the point value for this task to 3.
HCoplin-WMF edited projects, added MW-Interfaces-Team (MWI-Sprint-6 (2025-03-25 to 2025-04-08)); removed MW-Interfaces-Team (MWI-Sprint-5 (2025-03-11 to 2025-03-25)).Mar 25 2025, 2:34 PM
HCoplin-WMF assigned this task to • FGoodwin.Mar 25 2025, 3:19 PM
HCoplin-WMF edited projects, added MW-Interfaces-Team (MWI-Sprint-7 (2025-04-08 to 2025-04-22)); removed MW-Interfaces-Team (MWI-Sprint-6 (2025-03-25 to 2025-04-08)).Apr 8 2025, 3:20 PM
HCoplin-WMF removed • FGoodwin as the assignee of this task.Apr 23 2025, 4:16 PM
HCoplin-WMF edited projects, added MW-Interfaces-Team (MW-Sprint-8 (2025-04-23 to 2025-05-06)); removed MW-Interfaces-Team (MWI-Sprint-7 (2025-04-08 to 2025-04-22)).
HCoplin-WMF added a subscriber: • FGoodwin.
HCoplin-WMF edited projects, added MW-Interfaces-Team (MWI-Roadmap); removed MW-Interfaces-Team (MW-Sprint-8 (2025-04-23 to 2025-05-06)).Apr 23 2025, 4:38 PM
HCoplin-WMF edited projects, added MW-Interfaces-Team; removed MW-Interfaces-Team (MWI-Roadmap).Apr 29 2025, 1:36 PM
OWresch-WMF assigned this task to • FGoodwin.May 6 2025, 2:58 PM
OWresch-WMF edited projects, added MW-Interfaces-Team (MW-Sprint-8 (2025-04-23 to 2025-05-06)); removed MW-Interfaces-Team.
HCoplin-WMF edited projects, added MW-Interfaces-Team (MW-Sprint-9 (2025-05-07 to 2025-05-20)); removed MW-Interfaces-Team (MW-Sprint-8 (2025-04-23 to 2025-05-06)).May 9 2025, 6:12 PM
OWresch-WMF moved this task from Committed to In Progress on the MW-Interfaces-Team (MW-Sprint-9 (2025-05-07 to 2025-05-20)) board.May 12 2025, 3:24 PM
OWresch-WMF moved this task from In Progress to Committed on the MW-Interfaces-Team (MW-Sprint-9 (2025-05-07 to 2025-05-20)) board.May 19 2025, 3:11 PM
HCoplin-WMF edited projects, added MW-Interfaces-Team; removed MW-Interfaces-Team (MW-Sprint-9 (2025-05-07 to 2025-05-20)).May 20 2025, 3:02 PM
HCoplin-WMF reassigned this task from • FGoodwin to Atieno.May 20 2025, 3:27 PM
HCoplin-WMF moved this task from Next Up to MW-Sprint-10 (2025-05-20 to 2025-06-03) on the MW-Interfaces-Team board.
HCoplin-WMF edited projects, added MW-Interfaces-Team (MW-Sprint-10 (2025-05-20 to 2025-06-03)); removed MW-Interfaces-Team.
gerritbot added a comment.May 25 2025, 12:34 PM

Change #1149994 had a related patch set uploaded (by Atieno; author: Atieno):

[mediawiki/core@master] REST: Add translatable OpenAPI endpoint descriptions for all remaining endpoints

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

gerritbot added a project: Patch-For-Review.May 25 2025, 12:34 PM
Atieno moved this task from Committed to Code Review on the MW-Interfaces-Team (MW-Sprint-10 (2025-05-20 to 2025-06-03)) board.May 25 2025, 12:43 PM
Atieno updated the task description. (Show Details)
Atieno added a comment.May 26 2025, 1:41 PM

Hi @HCoplin-WMF The non-checked boxes are missing descriptions

HCoplin-WMF edited projects, added MW-Interfaces-Team (MWI-Sprint-11 (2025-06-03 to 2025-06-17)); removed MW-Interfaces-Team (MW-Sprint-10 (2025-05-20 to 2025-06-03)).Jun 3 2025, 3:20 PM
HCoplin-WMF moved this task from Committed to Code Review on the MW-Interfaces-Team (MWI-Sprint-11 (2025-06-03 to 2025-06-17)) board.
HCoplin-WMF added a comment.Jun 9 2025, 1:03 PM

Missing endpoint descriptions:

  • GET /page/{title}/history
    • Description: Returns information about the latest revisions to a wiki page, in segments of 20 revisions, starting with the latest revision. The response includes API routes for the next oldest, next newest, and latest revision segments, letting you scroll through page history.
  • GET /page/{title}/history/counts/{type}
    • Description: Returns basic data about a page's history, such as the number of edits made by different types of users, or how many reverts have occurred on the page. For more information and metrics to understand how readers and editors interact with Wikipedia and other Wikimedia projects, see the Analytics API.
  • GET /search
    • Description: Searches wiki pages for the given search terms, and returns matching pages.
  • POST /transform/wikitext/to/html/
    • Description: Converts any wikitext into HTML.
  • POST /transform/html/to/wikitext/
    • Description: Converts any HTML into wikitext.
  • POST /transform/wikitext/to/html/{title}
    • Description: Converts the wikitext of a given page to HTML. The wikitext request body parameter must be provided, but can be left empty to receive the full page. The response body contains the rendered HTML of the page.
  • POST /transform/html/to/wikitext/{title}
    • Description: Converts HTML of a given page to wikitext. The html request body parameter must be provided, but can be empty to receive the full page. The response body contains the wikitext of the page.
  • POST /transform/wikitext/to/html/{title}/{revision}
    • Description: Converts the wikitext of a given revision to HTML. The wikitext request body parameter must be provided, but can be left empty to receive the full revision. The response body contains the rendered HTML of the revision.
  • POST /transform/html/to/wikitext/{title}/{revision}
    • Description: Converts HTML of a given revision to wikitext. The html request body parameter must be provided, but can be empty to receive the full revision. The response body contains the wikitext of the revision.
gerritbot added a comment.Jun 13 2025, 6:00 AM

Change #1149994 merged by jenkins-bot:

[mediawiki/core@master] REST: Add translatable OpenAPI endpoint descriptions for all remaining endpoints

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

Maintenance_bot removed a project: Patch-For-Review.Jun 13 2025, 6:30 AM
ReleaseTaggerBot added a project: MW-1.45-notes (1.45.0-wmf.6; 2025-06-17).Jun 13 2025, 7:00 AM
Atieno moved this task from Code Review to Demo Ready! on the MW-Interfaces-Team (MWI-Sprint-11 (2025-06-03 to 2025-06-17)) board.Jun 17 2025, 2:29 PM
HCoplin-WMF closed this task as Resolved.Jul 1 2025, 12:34 PM

Marking as resolved so I can archive this sprint board. Added a follow up task here for the description changes that were missed: https://phabricator.wikimedia.org/T398309

OWresch-WMF mentioned this in T398409: Swagger UI Sandbox Global Release (TBD: attach existing tasks).Jul 2 2025, 9:01 AM
Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct. · Wikimedia Foundation · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL · Credits