Core Platform Team/Initiative/API Gateway/Documentation Plan

Overview
The API Gateway is a CPT initiative to create a rate-limited API proxy at api.wikimedia.org as part of the Platform Evolution program. The MVP scope includes the MediaWiki REST API (including page, media, history, and search endpoints) and the Feeds API, with the intention of adding APIs over time. As of July 24, 2020, the initiative is in the implementation phase. See the initiative page and Phabricator tag.


 * GET /feed/v1/{project}/{language}/announcements
 * GET /feed/v1/{project}/{language}/featured/{yyyy}/{mm}/{dd}
 * GET /feed/v1/{project}/{language}/onthisday/{type}/{mm}/{dd}
 * GET /core/v1/{project}/{language}/file/{title}
 * GET /core/v1/{project}/{language}/search/page
 * GET /core/v1/{project}/{language}/search/title
 * POST /core/v1/{project}/{language}/page
 * GET /core/v1/{project}/{language}/page/{title}
 * PUT /core/v1/{project}/{language}/page/{title}
 * GET /core/v1/{project}/{language}/page/{title}/bare
 * GET /core/v1/{project}/{language}/page/{title}/html
 * GET /core/v1/{project}/{language}/page/{title}/with_html
 * GET /core/v1/{project}/{language}/page/{title}/links/language
 * GET /core/v1/{project}/{language}/page/{title}/links/media
 * GET /core/v1/{project}/{language}/page/{title}/history
 * GET /core/v1/{project}/{language}/page/{title}/history/counts/{type}
 * GET /core/v1/{project}/{language}/revision/{id}/bare
 * GET /core/v1/{project}/{language}/revision/{from}/compare/{to}

The purpose of this document is to manage the planning and feedback process for the documentation for this project.

Components
Architecture diagram working draft


 * MediaWiki
 * The API Portal will be a MediaWiki instance at api.wikimedia.org (beta: api.wikimedia.beta.wmflabs.org)


 * WikimediaApiPortal skin (Phabricator project)
 * A MediaWiki skin providing the look-and-feel of the API Portal


 * WikimediaApiPortalOAuth extension (Phabricator project)
 * A MediaWiki extension running on the API Portal that interfaces with the OAuth extension on Meta-Wiki


 * OAuth extension on Meta-Wiki
 * Responsible for storing and managing OAuth clients

Documentation requirements

 * How to use the api.wikimedia.org API
 * How to use the OAuth 2.0 flow with the api.wikimedia.org API
 * Rate limiting policies
 * Links to other Wikimedia APIs and resources
 * Visual design similar to the prototype
 * Shared Wikimedia account login

OAuth 2.0 client management requirements

 * Developers can create, list, and disable OAuth 2.0 clients using a simplified interface
 * Visual and interaction design similar to the prototype

MVP scope

 * Manually created API reference docs and guides in English
 * Editing restricted to a docs-editors group while we stabilize the content and set up contribution flows (See T249834)
 * User feedback via talk pages and “Was this page helpful?” gadget
 * OAuth 2.0 client management interface
 * Strategy for reducing duplication between the the API portal and the existing docs for the MediaWiki REST API and Feeds API.
 * Pageview data for the API portal

Future scope

 * API sandbox
 * Translate extension
 * Contribution flow for volunteers
 * Automated reference docs integrated with translatewiki
 * Asynchronous review process for contributors

Out of scope

 * Updates to the UI of the OAuth special pages on Meta

Implementation strategy

 * Use MediaWiki as the content platform
 * Implement the visual design using a new MediaWiki skin, configured to look similar to the prototype. Certain items such as the behaviors/flyouts may differ since they would use styles from Bootstrap. In the future, the visual style can be implemented using the improved Vector skin.
 * Create an extension that provides a simple UI to create simple OAuth 2.0 clients as shown in the prototype.
 * The new extensions will only be installed on the API Portal.
 * The new extension will interact with the OAuth extension installed on Meta through an API.
 * The new extension will be named WikimediaApiPortal and could also contain other UI elements needed for the API Portal.
 * Attempt to limit any additional libraries necessary for the UI.

Naming and location
Proposed location: MediaWiki instance at:
 * api.wikimedia.org (preferred)
 * Alternatives:
 * developer.wikimedia.org (could be confusing due to the fact that these docs won’t have the comprehensive scope of a Wikimedia Developer Portal)
 * restapi.wikimedia.org
 * apiportal.wikimedia.org
 * webapi.wikimedia.org
 * apidev.wikimedia.org
 * apidoc.wikimedia.org
 * dev.wikimedia.org (exists as a redirect to a page on mediawiki.org)

Considerations
Due to the maintenance effort required to sustain a new public wiki, we should seek to balance the design requirements of this project with the principles and processes of the Wikimedia movement.

Open questions

 * ✅ Is there a way we could enable posting on talk pages without enabling editing of all pages?
 * Manual:Preventing access implies that Extension:Lockdown might be needed. --AKlapper (WMF) (talk) 17:09, 26 March 2020 (UTC)
 * (See T249834)

Prototype
View the API Portal prototype here, including:
 * Documentation intro page
 * API reference overview
 * Search pages reference
 * Community page
 * My account pages including create key popup

Documentation requirements

 * Overview of the implementation and configuration of the API Gateway and rate limiting system
 * How to manage rate limits
 * How to add and remove APIs from the Gateway

Implementation strategy
Proposed location: Wikitech TechOps docs

Objectives and metrics

 * Create a great developer experience for the Wikimedia API
 * Metric: Qualitative feedback from developer interviews


 * Make it easy for developers to get started
 * Metric: Percentage of visitors to the site who register an app
 * Metric: Percentage of registered apps with at least one API call


 * Make it easy for developers to build apps
 * Metric: Percentage of users with registered apps that have an app with more than five API calls