You are browsing a read-only backup copy of Wikitech. The live site can be found at wikitech.wikimedia.org

User:Alex Paskulin/API catalog

From Wikitech-static
< User:Alex Paskulin
Revision as of 23:53, 30 November 2021 by imported>Alex Paskulin (First draft of the API catalog page)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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.


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. The API catalog automatically discovers catalog-info.yaml files in the Wikimedia production cluster(?).

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: tag for RESTful APIs
spec.type

required | string

  • openapi for an OpenAPI spec in YAML or JSON format (version 2 or 3)
  • graphql for a GraphQL schema

For the complete list of supported types, visit the Backstage docs.

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.

Frequently asked questions

Questions and feedback

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