API catalog

From Wikitech

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.


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.