Change Details

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. ## API Portal mission statement The Wikimedia API Portal is an information hub for people creating, serving, and using Wikimedia-specific APIs. ## Personas - People who create APIs - People who use APIs - People who write API documentation - People who are responsible for the stability of WMF servers ## Capabilities - Allow for the discovery of **ALL** (new, old, experimental, public, internal, Gateway, non-Gateway, WMF, non-WMF) Wikimedia HTTP APIs through an API catalog - [Deprioritized] Serve API reference documentation created using the to-be-developed API Platform documentation tooling - Act as a multilingual wiki for API-related learning materials, like tutorials and best practices - Create and manage Wikimedia OAuth 2.0 clients ## Information architecture ### 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. Pages under Learn have a flat structure. The Learn landing page includes 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.) ### /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. Each API 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 creators. 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. 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. ## Content types - landing page - API page - topic - tutorial - code sample - process page - guideline ## Proposed structure and map to existing pages [Google Sheet](https://docs.google.com/spreadsheets/d/1u9XtdmuAOj5RQTL9tRVgnXD3TlZ_HdyU_DepVS8N8vM/edit#gid=0) (publicly viewable)

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. ## 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, an initiative to make it easier to develop, access, and maintain Wikimedia APIs. 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. **User journeys** (Work in progress) ## Information architecture ### 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. Pages under Learn have a flat structure. The Learn landing page includes 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.) ### /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. Each API 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 creators. 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. 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. ## Content types - landing page - API page - topic - tutorial - code sample - process page - guideline ## Proposed structure and map to existing pages [Google Sheet](https://docs.google.com/spreadsheets/d/1u9XtdmuAOj5RQTL9tRVgnXD3TlZ_HdyU_DepVS8N8vM/edit#gid=0) (publicly viewable)

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. ## API Portal mission statement## Scope The Wikimedia API Portal is an information hub for people creating, servingmaintaining, and using Wikimedia-specific APIs. ## PersonasIt provides documentation and collaboration spaces for the API Platform, an initiative to make it easier to develop, access, and maintain Wikimedia APIs. Some aspects of the API Portal will evolve as we develop a better understanding of the API Platform. - People who create APIsThe 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. - People who use APIsCreate 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. - People who write API documentation- **Inclusivity**: We strive to include the widest possible set of users and contributors. - People who are responsible for the stability of WMF serv**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 ## Capabilities### API users - Allow for the discovery of **ALL** (new, old,People who use Wikimedia APIs. experimentalThis is a broad group that includes WMF and affiliate developers, publicvolunteer developers, internalpartners, Gatewayresearchers, non-Gateway, WMF, non-WMF) Wikimedia HTTP APIs through anand students. **User journeys** - Learn how to use Wikimedia API catalogs. - [Deprioritized] Serve API reference document- Find information created using the to-be-developed API Platform documentation toolingabout a specific API. - Act as a multilingual wiki for API-related learning materialConnect 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, like tutorials and best practicesincluding WMF site reliability engineers. **User journeys** - Create and manage Wikimedia OAuth 2.0 clients(Work in progress) ## Information architecture ### 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. Pages under Learn have a flat structure. The Learn landing page includes 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.) ### /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. Each API 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 creators. 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. 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. ## Content types - landing page - API page - topic - tutorial - code sample - process page - guideline ## Proposed structure and map to existing pages [Google Sheet](https://docs.google.com/spreadsheets/d/1u9XtdmuAOj5RQTL9tRVgnXD3TlZ_HdyU_DepVS8N8vM/edit#gid=0) (publicly viewable)