RESTBase currently serves API reference documentation using OpenAPI specifications and Swagger UI. (See https://wikimedia.org/api/rest_v1/#/ and project-specific docs such as https://en.wikipedia.org/api/rest_v1/#/) With RESTBase planned for deprecation, this task is intended to start conversations about a new system for serving API reference docs to replace RESTBase.

This task does not cover other types of API documentation (tutorials, topics, etc.) or how to communicate RESTBase deprecation to API users. The overall discoverability of API docs, tutorials, and API-related topics is outside the scope of this task and is being worked on as part of the API Platform/API Portal project.

Until RESTBase shutdown

My assumption is that, regardless of how the API calls are routed, until RESTBase is shut down, RESTBase can continue to serve, for each project and for wikimedia.org:

• an OpenAPI spec (at /api/rest_v1/?spec)
• a swagger UI page pointed at the spec (at /api/rest_v1/)

If this assumption is correct, we can continue to serve documentation for the /api/rest_v1/ routes, as long as those routes are still supported, until RESTBase is completely turned off.

After RESTBase shutdown

If we still need to support the /api/rest_v1/ routes after RESTBase is shut off, we can (as a minimum viable option) fork the complete OpenAPI specs generated by RESTBase, store them elsewhere (doc.wikimedia.org or Toolforge), and create a simple portal for users to access them (using RapiDoc and either a wiki page, the API Portal, or a static page on doc.wikimedia.org or Toolforge).

Going beyond minimum viable, we could store the API spec for each service alongside the code and add an endpoint to the service that serves the spec publicly where it can be consumed by RapiDoc and presented to users.

Long term

Assuming there will be new routes to access these APIs (through the API Gateway or something else), we will want to work with each service involved to find a way to document the API so that we:

• Increase confidence in the accuracy in API docs: Although there are many ways to establish guarantees around accuracy, the common outcome is increased confidence in the docs.
• Integrate documentation into the API development process: Our objective is not to build documentation tooling in isolation, but to use this tooling to improve the API development process as a whole. Practically, this means focusing on the needs of API developers in building workflows to create and update the docs.

There are a lot of different ways to approach this, depending on the programming languages and frameworks used in each service and the workflows of the teams. Although it's not the only option, using OpenAPI gives us a lot of good opportunities to implement the docs in ways that are either generated from the code, generated from tests, or tested against API behavior. I'd also like to explore options for internationalizing API docs; see discussion on T322456.