API catalog

The API catalog is a list of Wikimedia APIs.
== About the API catalog ==
The API catalog is a project of the API Platform Team. The purpose of the catalog is to help API producers and consumers, primarily within the Wikimedia Foundation, discover and manage APIs. The API catalog is currently in the minimum viable product (MVP) phase and uses the open-source Backstage platform hosted on Toolforge.
Api-catalog-list-view.png|API catalog
Api-catalog-detail-view.png|API overview
Api-catalog-definition-view.png|API definition
== Add an API ==
=== MVP ===
For the MVP version of the catalog, you can add an API by uploading an API definition file to the catalog repository.
# Create an API definition file, and add it to the nikkin/backstage repository data/apis directory.
# Add the API definition filename to the spec.targets list in all-apis.yaml.
=== Early adopters ===
The API catalog supports automatic discovery of APIs stored or mirrored in the Wikimedia GitHub organization under mediawiki/services. Early adopters of the catalog can integrate an API by adding an API definition file to the root directory of the project repository. For example, here is the definition file for the Example Node API.
For projects whose repository name does not include mediawiki/services, you must manually import your API using the catalog interface.
== API definition ==
The API catalog uses YAML files to define APIs.
=== Example ===
As an example, here is the API definition for the Image Suggestion API.
=== Schema ===
For the complete schema, visit the Backstage docs.
apiVersion
required | string	Must be backstage.io/v1alpha1
kind
required | string	API for all APIs
metadata.name
required | string	Unique API name using lowercase letters and dashes
metadata.description
required | string	Short and informative overview of the API
metadata.tags
optional | list	List of tags to classify APIs by type and other attributes:
* rest: RESTful APIs
* rpc: RPC APIs
* ml: APIs related to machine learning
* sse: APIs using the Server-Sent Events protocol
Suggest a new tag by commenting on the talk page.
metadata.links
optional | list	Links to API documentation on wiki or other sites. Each link has these attributes:
* url: Complete link to the page
* title: Link text that appears in the catalog
* icon: Set this to docs, which renders as a simple page icon
spec.type
required | string	API specification standard used for the API reference docs, either:
* openapi for APIs with an OpenAPI spec in YAML or JSON format (version 2 or 3)
* graphql for a GraphQL API
* none for APIs documented in wikitext or other non-standard format
spec.lifecycle
required | string	Phase of API development, either:
* experimental: APIs that may change without notice
* stable: APIs that follow a backwards-compatible version policy
* deprecated: Deprecated APIs
spec.owner
required | string	Team maintaining the API, using lowercase letters and dashes
spec.definition.$text
required | string	For APIs with an OpenAPI spec or GraphQL schema, the link to the spec. If possible, link to a spec stored in a Wikimedia GitHub repository. For example, for the Image Suggestion API:
 definition:
 $text: https://github.com/wikimedia/mediawiki-services-image-suggestion-api/blob/master/spec.yaml
If the spec is generated dynamically or not stored in the project repository, add the host to the backend.reading.allow list in app-config.production.yaml to allow the catalog to read it.
For APIs without a machine-readable spec, use definition to describe how the API reference docs are created and where they are stored. For example, for the MediaWiki Action API:
 definition: |
 Docs generated by MediaWiki and served as HTML at
 https://www.mediawiki.org/w/api.php?action=help&modules=main
== Frequently asked questions ==
; What about the component catalog in Backstage?
: At this time, the API Platform Team is focused on cataloging APIs. Let us know if you're interested in a general Wikimedia service catalog.
== Questions and feedback ==
To share feedback or ask a question, comment on the talk page.