Description

To complete our implementation of interactive documentation and support our long term vision of validated specs, we need to define and document specific endpoint responses in JSON. This includes reusable object definitions (eg: page), happy path (eg: HTTP 20x) responses per endpoint, as well as common error (eg: HTTP 40x) responses that may be used across endpoints in some cases. This work is focused on taking the initial step of documenting a handful of endpoints that use common request and response structures, so that we can use these definitions to create and test a validation tool, then repeat the pattern across the rest of the MediaWiki REST API endpoints.

Problem statement
We need JSON representations of our response bodies so that we can build and test validation against them. We do not yet have an established pattern of where to store these files.

Conditions of acceptance

• Where it makes sense, define a reusable schema that can be referenced across endpoint responses.
  • Create a standard page definition that can be used for GET, PUT, and POST page responses.
  • Create standard responses for specific, broadly applicable error codes (eg: 40x).
• Start with the w/rest.php/v1/page endpoints. This includes:
  • POST: w/rest.php/v1/page
  • GET: w/rest.php/v1/page/{title}
  • PUT: w/rest.php/v1/page/{title}
• Translate the expected response bodies into JSON, including all expected responses:
  • 200: Update success
  • 201: Create success
  • 400: Bad Request
  • 401: Unauthorized
  • etc.
• Store the JSON files in a well known repo location. Talk to Daniel Kinzler about where they should be stored.

Out of scope

For now, only focus on the page endpoints. There will be a separate, follow up item to repeat this type of exercise with additional endpoints after the schema validator and reusable code exist. Similarly, this task is exclusively scoped to defining and storing the initial set of JSON files. Code to support validation and reusable snippets for encoding/decoding the JSON files will be covered in a separate body of work.