Description

RESTBase currently hosts its own OpenAPI specs. Following RESTBase sunsetting, we need a new location for hosting OpenAPI specs and enabling interactive API documentation.

Considerations

• APIs hosted through RESTBase vary based on configuration. Typically these configurations correspond to API family (eg: Wikipedia vs Wikctionary), meaning we do not expect nor need to support customizations for every wiki project. From a practical standpoint, this means ~5-6 variations in total.
• This is a temporary solution. The rest_v1 endpoints will eventually be on the end of life path. They are already being rerouted through MediaWiki Core APIs. We do not expect the rest_v1 endpoints to change and will eventually remove them entirely.
• This is a one-off solution. RESTBase has several API modules with different backend services bundled into a single spec. Looking ahead, we expect services to self-host their specs and allow them to be managed independently and fetched for use in the Sandbox.
• We do not want to create another mini-RESTBase.

Decision

We will store the RESTBase OpenAPI specs within the REST Gateway and implement custom logic to apply the correct spec per API family. The Existing docs page will reroute to the REST Sandbox for each Wiki project, where the Wikimedia REST APIs hosted through RESTBase are already visible.

Action items

• CTT is responsible for creating static OpenAPI specs for each required variation
  • CTT is responsible for defining logic of which spec should be used in each project family/community
• SRE (Hugh) will reroute api/rest_v1?spec endpoint within REST Gateway
• MWI will host and return the correct spec for each API family
  • Determine hosting location within MW
  • Return the correct spec based on the CTT provided logic
• Announce deprecation/rerouting of: /api/rest_v1 Swagger visualization
  • Redirect docs page to the REST Sandbox