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 March 6, 2020, the initiative is in the technical planning phase. See the initiative page and Phabricator tag.


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

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

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

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 credential management requirements

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

Site styles

 * Text: Text styles should match those described in the style guide with the exception of heading 1, which should use Georgia instead of Charter.
 * Colors: As described in the style guide,
 * Primary text color
 * #222
 * Sidebar text colors
 * #222
 * #3366CC
 * #000000
 * #54595D
 * Base colors
 * #fff
 * #f8f9fa
 * Accent colors
 * #eaf3ff
 * #36c
 * #eaecf0
 * Usage graph
 * #00af89
 * #d33
 * Notifications
 * #b32424
 * #ac6600
 * #36c
 * #72777d
 * #14866d

MVP scope

 * Manually created API reference docs and guides in English
 * Editing restricted to a docs-editors group
 * User feedback via email alias and “Was this page helpful?” gadget
 * OAuth 2.0 credential 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 in Meta.

Implementation strategy

 * Use MediaWiki as the content platform
 * Implement the visual design using the Chameleon skin, configured to look similar to the prototype. Certain items such as the behaviors/flyouts may differ since they would use styles from Bootstrap. We’ll need to coordinate with Stephan Gambke so he is aware in case we need to submit any pull requests to Chameleon. 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 consumers as shown in the prototype.
 * The new extension 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)
 * developer.wikimedia.org (preferred, could be confusing due to the fact that these docs won’t have the comprehensive scope of a Wikimedia Developer Portal)
 * Alternatives:
 * 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)

Permissions and moderation
Proposed groups and permissions for MVP:
 * Docs-editors group
 * Create pages
 * Edit pages
 * Logged-in users
 * Manage API keys
 * Anonymous users
 * View pages

For the MVP launch, the docs will be closed to volunteer editing while we stabilize the content and assess traffic and moderation needs. These editing restrictions also apply to talk pages since MediaWiki doesn't separate permissions for editing pages and posting to talk pages. The eventual goal will be to open the site to volunteer editing with the exception of rate limiting policy docs.

Feedback
For the MVP, feedback and questions will be handled through an email alias, monitored by User:APaskulin (WMF), and a "Was this page helpful?" Gadget similar to the one used on the mediawiki.org API docs.

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?