Description
Today, the example requests and responses simply reflect the type designations. For example, all integers show as 0, and all strings display "string" as the value. While this is a good starting point, this is insufficient in many cases to prepare users for what is expected or should be provided. For example, timestamps reflect "string" which does not reflect the specific format of the timestamp that needs to be provided or is expected to be returned (eg: "2020-06-20T20:05:55Z"), which frequently results in users guessing and struggling to submit a valid request. Providing users with more representative, real world examples will improve users' ability to discover the correct endpoints and execute requests through the Sandbox.
Conditions of acceptance
For all MediaWiki REST API endpoints:
- Update the JSON responses to better reflect what is actually expected in the response. (@apaskulin)
- Update placeholder text in sample request bodies to reflect the format of what is expected in an actual request.
- Update parameter placeholder text in the "Try it" workflows to reflect helpful examples. (Depends on T420988: Support examples for request parameters in OpenAPI descriptions)
- (Optional/Open for discussion) In cases where the request or response is a translatable object (for example, the content of a page), make it translatable via the translatewiki workflow.
Implementation Notes
In most cases, there are already detailed examples present in the MediaWiki reference documentation here: https://www.mediawiki.org/wiki/API:REST_API/Reference# . These may be used directly. In cases where examples do not exist or do not match current behavior, consult with Halley for recommendations on new examples.