MediaWiki Interfaces Team/Feature Feedback/REST Sandbox
Thank you for taking the time to review and provide feedback on the new MediaWiki REST Sandbox! For more information about the REST Sandbox feature, see the project background at the end of this document.
How to use this page?
[edit]The purpose of this page is to offer a central tracking mechanism for feedback related to the new REST Sandbox special page. Please feel free to use the discussion page to ask questions and respond to the open feedback prompts below. Additionally, if you create a new issue in Phabricator related to this feature, please feel free to add it the issue tracker table on this page directly.
Feature feedback
[edit]The MediaWiki interfaces team is seeking active feedback from the technical volunteer community on this feature. The REST Sandbox launched to all Wikimedia projects as part of the default configuration on Monday Oct 20, but we seek to continually iterate and improve this experience.
Open feedback prompts
[edit]In addition to surfacing specific issues that you've seen, please feel free to provide open feedback about your experience on the discussion page, and/or respond to any of the following prompts:
- Do you believe that providing the documentation in your wiki community's preferred language will help developers better understand the content?
- Are the translations accurate and appropriate in your preferred language?
- How do you intend to use the OpenAPI specs now available through the sandbox?
- How will the sandbox change how you interact with the MediaWiki REST API?
- Would you like to see similar experiences for other APIs offered by Wikimedia?
- As an extension author, would you leverage this experience to provide interactive documentation for your extension's API?
- What do you think about API Sandboxes (REST and Action) executing calls against production environments?
- Does that match your preferences or expectations?
- Have you (or anyone you know) ever made a mistake in a production environment while using the sandbox?
We are currently aware of and are working to resolve the following issues:
[edit]| Title | Description | Status | Phabricator | ECD |
|---|---|---|---|---|
| SwaggerUI translation | The REST sandbox uses Swagger UI for documentation visualization, which does not support native translation. This causes a less-than-ideal mixed experience for readers, where endpoint and parameter descriptions are translated, but overall UI elements (eg: table headers, button labels) remain in English. | In Progress | phab:T397474 | TBD |
| API info translation | MediaWiki REST API includes several strings that appear in the info section of OpenAPI specs. We have not yet added support for translating these values. | Done! | phab:T385855 | 4/11 |
| Endpoint descriptions | Endpoint descriptions are helpful for getting basic information about an endpoint's purpose. We have not yet added support for translating these values. | Done! | phab:T388528 phab:T388527 |
TBD |
| Distribution license issues | Swagger UI does not appropriately include license files in the js library bundle. We are determining the best approach for how to cover the missing licenses in the MediaWiki distribution. | Done! | phab:T382086 | 4/25 |
| Transform "Try it out" | "Try it out" capability does not work on the /v1/transform endpoints. | Done! | phab:T391712 | TBD |
| Specs API error | Error messages are displayed due to missing references for the "Specs API" | Pending | phab:T391715 | TBD |
Project background
[edit]Over the course of FY 24-25, we've introduced a new REST Sandbox special page. To power this experience, we generate an OpenAPI spec, then use Swagger UI for the documentation visualization and interactivity. Although we currently only offer sandbox support for MediaWiki REST APIs, we hope to create a reusable pattern that will make it easier to adopt across Wikimedia, so that we may begin offering more consistent documentation experiences.
The REST Sandbox offers four main benefits to Wikimedia developers using the MediaWiki REST API:
- Generated OpenAPI specifications: OpenAPI (fka: Swagger) specifications were a top requested API feature from the most recent developer satisfaction survey. OpenAPI is a standard format for defining REST APIs in a uniquely human and machine readable format. OpenAPI specs can be used for generating code and testing against the API, in addition to unlocking a variety of off-the-shelf tools for generating documentation and aiding with API deployment. We are now creating OpenAPI specs on demand, and making them available for download through the REST sandbox experience for MediaWiki APIs.
- Interactive documentation in a familiar format: Sandbox style documentation is another top requested API feature from the developer satisfaction survey. SwaggerUI is a well known, open source documentation visualization and sandbox solution. Several other RESTful Wikimedia projects also use Swagger UI, such as the Wikimedia REST API and Wikibase REST API; using the same style and navigation patterns reduces cognitive load when approaching a new API.
- Documentation translation and localization: The translatewiki community will support translation for the contents of the spec before visualizing it with Swagger UI. Although technical concepts (eg: parameter and property names; endpoint names) will remain in English, enabling developers to review the more descriptive documentation in their preferred language will make the Wikimedia developer experience more equitable to non-English speakers.
- Automated testing to ensure documentation accuracy: Behind the scenes, we are leveraging the OpenAPI spec to verify that the actual API behavior matches the API definition as part of our Continuous Integration (CI) testing. This will allow us to programmatically detect and prevent potential breaking changes, such as changes to the endpoint response body, which will improve endpoint stability.
Annual planning & related work
[edit]This work supports the 2024-2025 fiscal year annual plan for product and technology department to deliver on the WE5 objective, as well as KR 5.1 which state:
WE5: Knowledge platform I (Platform evolution): Evolve the MediaWiki platform and its interfaces to better meet Wikipedia's core needs. Key Result 5.1: By the end of Q3, complete at least 5 interventions that are intended to increase the sustainability of the platform.
Related FY 24-25 hypotheses:
[edit]- WE 5.1.3: If we reroute the endpoints currently exposed under rest_v1/page/html and rest_v1/page/title paths to comparable MW content endpoints, then we can unblock RESTbase sunsetting without disrupting clients in Q1.
- WE 5.1.7: If we represent all content module endpoint responses (10 in total) in our MediaWiki REST API OpenAPI spec definitions, we will be able to implement programmatic validation to guarantee that our generated documentation matches the actual responses returned in code.
- WE 5.1.8: If we introduce support for endpoint description translation (ie: does not include actual object definitions or payloads) into our generated MediaWiki REST API OpenAPI specs, we can lay the foundation to support Wikimedia’s expected internationalization standards.
- WE 5.1.12: If we release an interactive documentation sandbox for MediaWiki REST APIs, it will introduce a repeatable pattern for low maintenance, high quality API documentation while making the APIs easier to adopt for developers around the world. This will ensure that our API documentation is fully up to date, testable, and localised for generations of developers, while reducing the maintenance cost and increasing sustainability for API publishers.