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: Difference between revisions

From Wikitech-static
Jump to navigation Jump to search
imported>Alex Paskulin
m (Shorten heading)
imported>Alex Paskulin
(Alex Paskulin moved page User:Alex Paskulin/API catalog to API catalog: Moving out of user page)
 
Line 1: Line 1:
{{Draft}}
#REDIRECT [[API catalog]]
 
The API catalog is a list of Wikimedia APIs.
 
{{Clickable button 2|Browse the API catalog|class=mw-ui-progressive|url=https://backstage-api-catalog.toolforge.org/api-docs}}
 
== 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 the minimum viable product (MVP) phase and uses the open-source [https://backstage.io/ Backstage] platform hosted on Toolforge.
 
 
<gallery>
Placeholder view vector.svg|API catalog
Placeholder view vector.svg|API overview
Placeholder view vector.svg|API definition
</gallery>
 
== 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.
 
# 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].
# 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
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 [https://backstage.io/docs/features/software-catalog/descriptor-format Backstage docs].
 
{| class="wikitable" style="width: 100%;"
|style="width: 20%;"|<code>apiVersion</code>
<small>required | string</small>
| Must be <code>backstage.io/v1alpha1</code>
|-
| <code>kind</code>
<small>required | string</small>
| <code>API</code> for all APIs
|-
| <code>metadata.name</code>
<small>required | string</small>
| Unique API name using lowercase letters and dashes
|-
| <code>metadata.description</code>
<small>required | string</small>
| Short and informative overview of the API
|-
| <code>metadata.tags</code>
<small>optional | list</small>
| List of tags to classify APIs by type and other attributes:
* <code>rest</code>: RESTful APIs
* <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>
<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>graphql</code> for a GraphQL API
* <code>none</code> for APIs documented in wikitext or other non-standard format
|-
| <code>spec.lifecycle</code>
<small>required | string</small>
| 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>
<small>required | string</small>
| Team maintaining the API, using lowercase letters and dashes
|-
| <code>spec.definition.$text</code>
<small>required | string</small>
| 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>
 
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.
 
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 ==
 
; 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.

Latest revision as of 18:16, 12 January 2022

Redirect to:

Retrieved from "https://wikitech-static.wikimedia.org/w/index.php?title=User:Alex_Paskulin/API_catalog&oldid=585889"