User:Alex Paskulin/API catalog

The API catalog is a list of Wikimedia APIs.

Browse the API catalog

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

• 

  API overview

• 

  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.

1. Create an API definition file, and add it to the nikkin/backstage repository data/apis directory.
2. 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.

image-suggestion-api.yaml

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: image-suggestion-api
  description: Suggests images to add to an article
  tags:
    - rest
    - ml
  links:
    - url: https://www.mediawiki.org/wiki/Core_Platform_Team/Initiatives/Image_Suggestion_API
      title: Wiki page
      icon: docs
spec:
  type: openapi
  lifecycle: experimental
  owner: platform-engineering-team
  definition:
    $text: https://github.com/wikimedia/mediawiki-services-image-suggestion-api/blob/master/spec.yaml

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.