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

User:Alex Paskulin/API catalog: Difference between revisions

From Wikitech-static
Jump to navigation Jump to search
imported>Alex Paskulin
imported>Alex Paskulin
m (Shorten heading)
Line 7: Line 7:
== About the API catalog ==
== About the API catalog ==


The API catalog is a project of the [[mw:Core_Platform_Team/Initiatives/API_Platform|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 [https://backstage.io/ Backstage] platform hosted on Toolforge.
The API catalog is a project of the [[mw:Core_Platform_Team/Initiatives/API_Platform|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 [https://backstage.io/ Backstage] platform hosted on Toolforge.




Line 16: Line 16:
</gallery>
</gallery>


== Add an API to the catalog ==
== Add an API ==


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?]
=== MVP ===


=== catalog-info.yaml example ===
For the MVP version of the catalog, you can add an API by uploading an API definition file to the catalog repository.


{{Codesample|name=catalog.yaml|lang=yaml|scheme=light|code=
# Create an [[#API_definition|API definition file]], and add it to the nikkin/backstage repository [https://gitlab.wikimedia.org/nikkin/backstage/-/tree/main/data/apis data/apis directory].
# Wikimedia API catalog descriptor file
# Add the API definition filename to the <code>spec.targets</code> list in [https://gitlab.wikimedia.org/nikkin/backstage/-/blob/main/data/all-apis.yaml 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 [https://github.com/wikimedia/mediawiki-services-example-node-api/blob/master/catalog-info.yaml definition file for the Example Node API].
 
For projects whose repository name does not include mediawiki/services, you must manually [https://backstage-api-catalog.toolforge.org/catalog-import 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.
 
{{Codesample|name=image-suggestion-api.yaml|lang=yaml|scheme=light|code=
apiVersion: backstage.io/v1alpha1
apiVersion: backstage.io/v1alpha1
kind: API
kind: API
metadata:
metadata:
   name: example-api
   name: image-suggestion-api
   description: an example node api
   description: Suggests images to add to an article
   tags:
   tags:
     - rest
     - rest
    - ml
  links:
    - url: https://www.mediawiki.org/wiki/Core_Platform_Team/Initiatives/Image_Suggestion_API
      title: Wiki page
      icon: docs
spec:
spec:
   type: openapi
   type: openapi
   lifecycle: production
   lifecycle: experimental
   owner: Platform Engineering Team
   owner: platform-engineering-team
   definition:
   definition:
     $text: ./spec.yaml
     $text: https://github.com/wikimedia/mediawiki-services-image-suggestion-api/blob/master/spec.yaml
}}
}}


=== catalog-info.yaml schema ===
=== Schema ===


For the complete schema, visit the [https://backstage.io/docs/features/software-catalog/descriptor-format Backstage docs].
For the complete schema, visit the [https://backstage.io/docs/features/software-catalog/descriptor-format Backstage docs].
Line 62: Line 83:
| <code>metadata.tags</code>
| <code>metadata.tags</code>
<small>optional | list</small>
<small>optional | list</small>
| List of tags to classify APIs by type and other attributes
| List of tags to classify APIs by type and other attributes:
* <code>rest</code>: RESTful APIs
* <code>rest</code>: RESTful APIs
* <code>gateway</code>: APIs using the [[API Gateway]]
* <code>rpc</code>: RPC APIs
* <code>ml</code>: APIs related to machine learning
* <code>sse</code>: APIs using the [[w:Server-sent_events|Server-Sent Events]] protocol
Suggest a new tag by commenting on the talk page.
|-
| <code>metadata.links</code>
<small>optional | list</small>
| Links to API documentation on wiki or other sites. Each link has these attributes:
* <code>url</code>: Complete link to the page
* <code>title</code>: Link text that appears in the catalog
* <code>icon</code>: Set this to <code>docs</code>, which renders as a simple page icon
|-
|-
| <code>spec.type</code>
| <code>spec.type</code>
<small>required | string</small>
<small>required | string</small>
|
| API specification standard used for the API reference docs, either:
* <code>openapi</code> for APIs with an OpenAPI spec in YAML or JSON format (version 2 or 3)
* <code>openapi</code> for APIs with an OpenAPI spec in YAML or JSON format (version 2 or 3)
* <code>graphql</code> for a GraphQL API
* <code>graphql</code> for a GraphQL API
* <code>none</code> for APIs without a spec in a standard format
* <code>none</code> for APIs documented in wikitext or other non-standard format
|-
|-
| <code>spec.lifecycle</code>
| <code>spec.lifecycle</code>
<small>required | string</small>
<small>required | string</small>
| To do: Add these
| Phase of API development, either:
* <code>experimental</code>: APIs that may change without notice
* <code>stable</code>: APIs that follow a backwards-compatible version policy
* <code>deprecated</code>: Deprecated APIs
|-
|-
| <code>spec.owner</code>
| <code>spec.owner</code>
<small>required | string</small>
<small>required | string</small>
| To do: Figure this out
| Team maintaining the API, using lowercase letters and dashes
|-
|-
| <code>spec.definition.$text</code>
| <code>spec.definition.$text</code>
<small>required | string</small>
<small>required | string</small>
| Location of the API spec relative to the project's root directory.  
| 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:
|}
<syntaxhighlight lang="yaml">
  definition:
    $text: https://github.com/wikimedia/mediawiki-services-image-suggestion-api/blob/master/spec.yaml
</syntaxhighlight>


=== Alternative workflow: Manual upload ===
If the spec is generated dynamically or not stored in the project repository, add the host to the <code>backend.reading.allow</code> list in [https://gitlab.wikimedia.org/nikkin/backstage/-/blob/main/app-config.production.yaml app-config.production.yaml] to allow the catalog to read it.


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].
For APIs without a machine-readable spec, use <code>definition</code> to describe how the API reference docs are created and where they are stored. For example, for the MediaWiki Action API:
<syntaxhighlight lang="yaml">
  definition: |
    Docs generated by MediaWiki and served as HTML at
    https://www.mediawiki.org/w/api.php?action=help&modules=main
</syntaxhighlight>
|}


== Frequently asked questions ==
== 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 ==
== Questions and feedback ==


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

Revision as of 21:18, 10 January 2022

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.