Description

The new REST Sandbox is intended to be the central location for discovering, reviewing, and testing Wikimedia REST APIs. However, only the MediaWiki (and soon Wikimedia/fka RESTBase) APIs are present. Several other REST APIs exist outside of the MediaWiki ecosystem, and we need a standard way to pull them in.

Conditions of acceptance

• Recommend a mechanism that allows external APIs to register specs for display in the REST Sandbox.
  • Assume that specs are stored externally, but an endpoint is available to request the latest spec.
  • Provide a mechanism to specify which project types the API is available for, if it is not controlled through other MediaWiki configuration options, like extensions.
  • Assume that the spec self-specifies the default server, regardless of which wiki it's being accessed from.
  • Assume that additional specs may not be translated; only those generated in MediaWiki are guaranteed to be translatable.
• Create a proof of concept/implementation proposal.
• Clearly document requirements for registration.
• [Stretch/Nice to have] Consider a method for creating standard format URLs for pulling specs, such that end users may expect a single URL format for pulling specs for any API. We can also revisit this as we move towards unified URL & module structures.

Implementation details

Many of the existing APIs already have OpenAPI specs that are either generated on demand or hosted in other locations. We can also expect more APIs to spin up as independent services in the future. Current examples include:

• AQS --> Assume this will be the guinea pig for pulling in as an external spec; TBD where their specs actually live (open question in #talk-to-data-engineering)
• Wikidata --> TBD if this will be included natively within the scope of the generated sandbox across wiki projects.
• API Portal APIs (eg: Liftwing, Recommendations) --> OpenAPI spec not available yet; will be in the future.

Today, this is accomplished through MediaWiki config.