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

Difference between revisions of "User:Alex Paskulin/API catalog"

From Wikitech-static
Jump to navigation Jump to search
imported>Nikki Nikkhoui
imported>Nikki Nikkhoui
Line 3: Line 3:
The API catalog is a list of Wikimedia APIs.
The API catalog is a list of Wikimedia APIs.


{{Clickable button 2|Browse the API catalog|class=mw-ui-progressive|url=https://backstage.toolforge.org/api-docs}}
{{Clickable button 2|Browse the API catalog|class=mw-ui-progressive|url=https://backstage-api-catalog.toolforge.org/api-docs}}


== About the API catalog ==
== About the API catalog ==
Line 87: Line 87:
=== Alternative workflow: Manual upload ===
=== 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 [https://gitlab.wikimedia.org/addshore/backstage/-/tree/main/data/apis data/apis directory].
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 [https://gitlab.wikimedia.org/nikkin/backstage/-/tree/main/data/apis data/apis directory].


== Frequently asked questions ==
== Frequently asked questions ==

Revision as of 15:41, 3 December 2021

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. 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: 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.