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 beta and uses the open-source Backstage platform hosted on Toolforge.

• 

  API catalog

• 

  API overview

• 

  API definition

Add an API to the catalog

To add an API to the catalog, add a catalog-info.yaml file to the root directory of your project repository. For projects whose repository name includes "mediawiki/services" and exists in the Wikimedia GitHub organization, the API catalog will automatically discover and load the API information into Backstage. For projects whose repository name does not include "mediawiki/services", you must manually add the URL to your project's catalog-info.yaml file to Backstage. [add screenshots of UI?]

catalog-info.yaml example

catalog.yaml

# Wikimedia API catalog descriptor file
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: example-api
  description: an example node api
  tags:
    - rest
spec:
  type: openapi
  lifecycle: production
  owner: Platform Engineering Team
  definition:
    $text: ./spec.yaml

catalog-info.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 gateway: APIs using the API Gateway
spec.type required | string	openapi for APIs with an OpenAPI spec in YAML or JSON format (version 2 or 3) graphql for a GraphQL API none for APIs without a spec in a standard format
spec.lifecycle required | string	To do: Add these
spec.owner required | string	To do: Figure this out
spec.definition.$text required | string	Location of the API spec relative to the project's root directory.

Alternative workflow: Manual upload

Instead of adding a file to the project repository, you can add an API to the catalog by uploading a catalog-info.yaml file to the Backstage repository data/apis directory.

Questions and feedback

To share feedback or ask a question, comment on the talk page.