Description

Community tech recently created two new endpoints that enable sitemap creation and page navigation: https://phabricator.wikimedia.org/T396684

Because these APIs were added to MediaWiki Core, they are automatically included in the [[ https://test.wikipedia.org/wiki/Special:RestSandbox | REST Sandbox ]]documentation. However, a few key elements are missing for spec generation, which creates a confusing and slightly misleading documentation experience.

The purpose of this ticket is to update the sitemap documentation to match existing MediaWiki API standards.

Conditions of acceptance.

To meet the standards we are trying to create around the REST Sandbox, please make the following changes:

• Create example response bodies. Please note that MWI REST APIs currently have examples of how to do this in JSON, but this will be the first XML response example set.
• Specify the correct accept-type (currently set as application/json; should be application/xml based on response) request header.
• Provide endpoint descriptions. Suggestions are below:
  • GET /site/v1/sitemap/{indexId}: Returns an XML list of available pages within the sitemap. The index default is 0; the presence of additional indices will be listed in robots.txt. Up to 10,000 pages are associated with each index.
  • GET /site/v1/sitemap/{indexId}/page/{fileId}: Returns an XML list of articles present on the site. Each entry contains a URL to the page and the last modified date. Each page contains up to 10000 URL entries.
• Provide endpoint summaries/short names. Suggestions are below:
  • GET /site/v1/sitemap/{indexId}: Get a list of sitemap pages
  • GET /site/v1/sitemap/{indexId}/page/{fileId}: Get a list of article locations per page
• Improve parameter descriptions. Suggestions are below:
  • IndexId: The sitemap index, starting at 0. Additional available indices are specified in robots.txt.
  • fileId: The desired page of articles.
• Consider renaming parameter on GET /site/v1/sitemap/{indexId}/page/{fileId} to {pageId} to match the route entity name
• Enable translation for the improved descriptions.

Risks & Blockers:
The MediaWiki Interfaces team does not have documentation available that outlines how to make these changes. Additionally, because MWI is currently doing a major refactoring effort in this area of code, any user guide that we do create will immediately become out of date. Because of these factors, MWI will implement these changes instead of the API owner (Tim S), and will focus on creating an accurate user guide along the way. In the future, we will expect API owners to be responsible for ensuring high quality endpoints and documentation.