Based on the [current content strategy](https://wikitech.wikimedia.org/wiki/API_Portal#Content_strategy) and the new scope defined in T289183, define a new content strategy for the API Portal.
## tl;dr
Instead of presenting a single, unified Wikimedia API in the API Portal, expose the complexity of the current systems by presenting each API as stand alone in terms of functionality and conventions. To manage this complexity for new API users, create a section of learning resources organized by topic and task, instead of by API.
## Scope
The Wikimedia API Portal is an information hub for people creating, maintaining, and using Wikimedia-specific APIs. It provides documentation and collaboration spaces for the API Platform initiative. Some aspects of the API Portal will evolve as we develop a better understanding of the API Platform.
The API Portal has these main objectives:
- Allow for the discovery of Wikimedia APIs through an API catalog.
- Act as a multilingual wiki for API-related learning materials, such as tutorials.
- Create and manage Wikimedia OAuth 2.0 clients.
Since the API Portal is specific to Wikimedia APIs, it is not a replacement for the Action API and Core REST API docs on mediawiki.org, which apply to any MediaWiki installation. The API Portal replaces the [[ https://www.mediawiki.org/wiki/Web_APIs_hub | Web APIs hub ]] and can eventually replace on-wiki docs for Wikimedia-specific APIs such as the [[ https://www.mediawiki.org/wiki/Wikimedia_REST_API | RESTBase API ]] and the [[ https://wikitech.wikimedia.org/wiki/Analytics/AQS/Pageviews | Pageviews API ]]. Without tooling to integrate OpenAPI with MediaWiki, the API Portal cannot replace OpenAPI documentation such as for the [[ https://en.wikipedia.org/api/rest_v1/ | RESTBase API ]].
## Principles
- **Transparency**: Our documentation, processes, and collaboration are publicly available.
- **Inclusivity**: We strive to include the widest possible set of users and contributors.
- **Trust**: Incorrect API documentation is worse than no API documentation. To maintain the API Portal as a trusted source of information, we prioritize documentation that includes a process for keeping it up to date.
## Users
#### API users
People who use Wikimedia APIs. This is a broad group that includes WMF and affiliate developers, volunteer developers, partners, researchers, and students.
**User journeys**
- Learn how to use Wikimedia APIs.
- Find information about a specific API.
- Connect with other API users.
- Get help.
#### API creators and maintainers
People who create or maintain Wikimedia APIs, including WMF and affiliate developers, product managers, and volunteer developers.
**User journeys**
(Work in progress)
#### WMF server maintainers
People who are responsible for the stability of Wikimedia Foundation servers, including WMF site reliability engineers and Meta-Wiki OAuth admins.
**User journeys**
(Work in progress)
## Information architecture
This section describes the planned information architecture to serve the scope and users defined above. This information architecture is designed so that it can be implemented immediately, without any dependencies on new policies or features, so that the API Portal can support the API Platform as it develops.
#### Overview
- **/Learn**: code samples, tutorials, and topics that teach people how to use Wikimedia APIs
- **/API catalog**: a list of available Wikimedia APIs, each with an API pages providing information about the API and links to docs
- **/Community**: resources for connecting the API community and helping them share their work, including announcements, featured projects, and contributing instructions
- **/API guidelines**: resources for API creators, including the API guidelines, process for adding an API, and other best practices
#### /Learn
The Learn section provides code samples, tutorials, and topics that teach people how to use Wikimedia APIs. This content is meant to be supplementary to API reference docs and primarily used by beginners and first-time users. Within the Learn section, editors can contribute code samples, tutorials, and topics using a set of standard templates.
Learn pages have a flat structure. The Learn landing page includes a link to the get started flow, a list of featured tutorials, related sets of pages, and ways to browse pages by tags. (The specific tagging system and mechanism are to be determined.)
**User journeys**
- Learn how to use Wikimedia APIs.
**Content types**
- **topic**: an explanation of a technical subject, such as a versioning policy or authentication guide
- **tutorial**: a series of steps which teaches the reader how to do something, such as a getting started guide
- **code sample**: a section of code that demonstrates a feature or best practice, with an explanation of how it works, designed to be easily reused
#### /API catalog
The API catalog lets users browse a list of available Wikimedia APIs. To reflect the current state of Wikimedia APIs, each API in the catalog is considered a stand-alone API in terms of functionality and conventions. The API catalog is manually curated, replacing the existing Backstage integration.
Each item in the catalog links to an API page. An API page is the home of an API; it acts as a central information hub and communication point between an API’s users and maintainers. The API page includes information about the API, commenting via the talk page, a link to the reference documentation, and links to relevant Learn pages. Here's an example of an WIP API page for the [Device Analytics API](https://api.wikimedia.org/wiki/Device_Analytics_API).
Subpages of the API page can be used for API reference documentation or for topics specific to that API. However, API reference documentation does not have to be stored in the API Portal. As long as the API reference meets the requirements for guaranteed accuracy (as set by the API guidelines), the docs can be stored anywhere and be discovered through the link on the API page.
**User journeys**
- Find information about a specific API.
**Content types**
- **API page**: central information hub for an API, including information about the API and links to documentation
- **reference page**: reference documentation for an API endpoint or resource
- **topic**: an explanation of a technical subject, such as a versioning policy or authentication guide
#### /Community
This section includes resources for connecting the API community and helping them share their work, including links to blog posts, announcements, featured projects, and contributing instructions.
**User journeys**
- Connect with other API users.
**Content types**
- **topic**: an explanation of a technical subject, such as a versioning policy or authentication guide
#### /API guidelines
This section includes resources for API creators, including the API guidelines, process for adding an API, and other best practices.
**User journeys**
- (Work in progress)
**Content types**
- **topic**: an explanation of a technical subject, such as a versioning policy or authentication guide
- **guidelines**: a set of recommendations informed by standards and best practices
## Content types
- **landing page**: a navigation page that links to related resources
- **API page**: central information hub for an API, including information about the API and links to documentation
- **reference page**: reference documentation for an API endpoint or resource
- **topic**: an explanation of a technical subject, such as a versioning policy or authentication guide
- **tutorial**: a series of steps which teaches the reader how to do something, such as a getting started guide
- **code sample**: a section of code that demonstrates a feature or best practice, with an explanation of how it works, designed to be easily reused
- **guidelines**: a set of recommendations informed by standards and best practices
## Proposed structure and map to existing pages
[Google Sheet](https://docs.google.com/spreadsheets/d/1u9XtdmuAOj5RQTL9tRVgnXD3TlZ_HdyU_DepVS8N8vM/edit#gid=0) (publicly viewable)
NOTE: As the sidebar functionality in the API Portal skin is currently built, API pages must be stored at `/My_API`, not `/API_catalog/My_API`. This also applies to pages in the Learn section (`/Get_started` instead of `/Learn/Get_started`). If structured URLs are an important requirement, we should prioritize adding a feature to the skin to provide more control over when the sidebar appears.
## Permissions
Allow edits by all logged-in users on all pages. Remove the current restrictions to allow default editing of user pages.
## Implementation plan
Phases and tasks to be created
**Phase 1: Set up new content**
- {T329808}
- Create an API page for the Core REST API
- Create an API page for the Feed API
- Create an API page for the Link recommendation API
- Create an API page for the Page description API
- Create an API page template
- Replace Backstage-integrated API catalog with on-wiki API pages
**Phase 2: Redirect existing content**
- Redirect pages from /API reference to /API catalog
- Redirect pages from /Documentation to /Learn
**Phase 3: Clean up and operationalize**
- Update homepage
- Update permissions
- Update contributing instructions
- Update about page
**Phase 4: Build out processes for /Learn**
- Create a tutorial template
- Create a code sample template
- Create a topic template
- Experiment with automation for creating /Learn content
- Experiment with tagging system for /Learn content