One nice thing about HyperSwitch is that it automatically creates an API sandbox for experimenting with an API using the OpenAPI 3.0 definition for the API.
It might be useful to have an API sandbox for RESTful APIs in MediaWiki. Open questions: would they be hand-coded, or automatically generated? If the latter, would there then be a way to provide an OpenAPI 3.0 definition to the system? Or would the sandbox layout be defined some other way?
| Status | Subtype | Assigned | Task | ||
|---|---|---|---|---|---|
| Invalid | None | T237565 REST API Infrastructure in MediaWiki | |||
| Resolved | BPirkle | T221742 REST API Sandbox in MediaWiki | |||
| Resolved | BPirkle | T388399 Add translation disclaimer to REST API Sandbox |
Automatically generated is the only sane way (the metadata it is generated from will of course have to be hand-maintained to some extent, just like the OpenAPI specs are).
The biggest shortcoming of the hyperswitch/swagger-ui sandboxes compared to the action API sandbox is probably lack of internationalization (an architecture principle now!). Seems generally not well supported in the OpenAPI spec currently. Other than that they seem mostly on par (except the action API sandbox not documenting response formats, which is definitely a huge pain point, although once you are tightly integrated with MediaWiki, it probably becomes more complicated). The action API sandbox has better UX (autocompletion, permalinks etc.) but that can probably be added to any metadata format.
One thing to consider here is that we'll want to implement some APIs outside of MediaWiki, for security reasons (everything related to authentication, for starters), but we'll probably want the same sandbox look & feel for them. So either the there should be a way to host a sandbox in MediaWiki without hosting the API, or the sandbox should be librarized and reusable outside of MediaWiki.
Forgive me if I'm misunderstanding, but isn't this already provided at Special:ApiSandbox, i.e. https://en.wikipedia.org/wiki/Special:ApiSandbox
SwaggerUI would give use this for free, see T323786: REST framework: Add support for outputting an OpenAPI (swagger) spec
REST Sandbox is live on test and beta. For example:
https://en.wikipedia.beta.wmflabs.org/wiki/Special:RestSandbox
We're still working through internationalization, and for providing spec details for all endpoints.
Lots to do on the REST Sandbox, but not under this task - there are already separate tasks for that work. Closing this task as resolved.