Page MenuHomePhabricator
Create Task
Maniphest T388527

Add translatable OpenAPI endpoint descriptions for all content 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:

  • POST /page
  • PUT /page/{title}
  • GET /page/{title}
  • GET /page/{title}/html
  • GET /page/{title}/with_html
  • GET /page/{title}/bare
  • GET /revision/{id}
  • GET /revision/{id}/html
  • GET /revision/{id}/with_html
  • GET /revision/{id}/bare
  • 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 localizable endpoint descriptions to content OpenAPI specsmediawiki/coremaster+78 -15
REST: Fix component definition schema to support i18nmediawiki/coremaster+42 -2
REST: rename "OAS" route config section to "openApiSpec"mediawiki/coremaster+4 -4
Customize query in gerrit

Related Objects
Search...

Event Timeline

HCoplin-WMF created this task.Mar 11 2025, 1:12 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:47 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 5.
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
• FGoodwin changed the task status from Open to In Progress.Mar 31 2025, 3:00 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 assigned this task to BPirkle.Apr 23 2025, 4:35 PM
HCoplin-WMF changed the point value for this task from 5 to 3.Apr 23 2025, 4:43 PM
gerritbot added a comment.Apr 24 2025, 7:24 PM

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

[mediawiki/core@master] REST: add localizable endpoint description to content module OpenAPI spec

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

gerritbot added a project: Patch-For-Review.Apr 24 2025, 7:24 PM
BPirkle moved this task from Committed to Code Review on the MW-Interfaces-Team (MW-Sprint-8 (2025-04-23 to 2025-05-06)) board.Apr 25 2025, 3:31 PM
BPirkle added a comment.May 3 2025, 5:45 PM

Per the task description:

If there are endpoints that are missing descriptions in the portal, consult with Halley for generating a new description.

@HCoplin-WMF , please review:

"rest-endpoint-desc-get-revision-id": "Returns meta-data for a revision, including source",
"rest-endpoint-desc-get-revision-id-html": "Returns the content of a revision in HTML. This endpoint returns content type text/html.",
"rest-endpoint-desc-get-revision-id-with-html": "Returns meta-data for a revision, including the content in HTML",

See en.json in the gerrit change for comparison to the similar page endpoints whose descriptions came from the API Portal.

I also shortened the PUT /page/{title} endpoint endpoint description from:

Edits a page based on the page's latest revision ID, or creates the page if no revision ID is given. To get the latest version of a page's source and revision ID, call the get page source endpoint. Most wiki pages are written in MediaWiki-flavored Wikitext.

In the event of a merge conflict, the API attempts to resolve the conflict automatically. If the edit conflict cannot be resolved, the API returns a 409 error.

To just:

Edits a page based on the page's latest revision ID, or creates the page if no revision ID is given.

So let me know what you think of that too.

gerritbot added a comment.May 3 2025, 5:48 PM

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

[mediawiki/core@master] REST: rename "OAS" route config section to "OpenApiSpec"

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

gerritbot added a comment.May 7 2025, 9:33 AM

Change #1141222 merged by jenkins-bot:

[mediawiki/core@master] REST: rename "OAS" route config section to "openApiSpec"

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

ReleaseTaggerBot added a project: MW-1.45-notes (1.45.0-wmf.1; 2025-05-13).May 7 2025, 10:00 AM
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
HCoplin-WMF moved this task from Committed to Code Review on the MW-Interfaces-Team (MW-Sprint-9 (2025-05-07 to 2025-05-20)) board.
gerritbot added a comment.May 11 2025, 4:18 PM

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

[mediawiki/core@master] REST: Fix component definition schema to support i18n

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

gerritbot added a comment.May 14 2025, 10:29 PM

Change #1143965 merged by jenkins-bot:

[mediawiki/core@master] REST: Fix component definition schema to support i18n

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

ReleaseTaggerBot edited projects, added MW-1.45-notes (1.45.0-wmf.2; 2025-05-20); removed MW-1.45-notes (1.45.0-wmf.1; 2025-05-13).May 14 2025, 11:00 PM
gerritbot added a comment.May 15 2025, 8:00 AM

Change #1138901 merged by jenkins-bot:

[mediawiki/core@master] REST: add localizable endpoint descriptions to content OpenAPI specs

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

Maintenance_bot removed a project: Patch-For-Review.May 15 2025, 8:30 AM
BPirkle updated the task description. (Show Details)May 15 2025, 3:00 PM
BPirkle moved this task from Code Review to Demo Ready! on the MW-Interfaces-Team (MW-Sprint-9 (2025-05-07 to 2025-05-20)) board.
HCoplin-WMF closed this task as Resolved.May 20 2025, 4:35 PM
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