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
(First draft of the API catalog page)
 
imported>Alex Paskulin
(Alex Paskulin moved page User:Alex Paskulin/API catalog to API catalog: Moving out of user page)
 
(4 intermediate revisions by 2 users not shown)
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.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 beta 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 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 ===
 
{{Codesample|name=catalog.yaml|lang=yaml|scheme=light|code=
# 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 [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>: tag for RESTful APIs
|-
| <code>spec.type</code>
<small>required | string</small>
|
* <code>openapi</code> for an OpenAPI spec in YAML or JSON format (version 2 or 3)
* <code>graphql</code> for a GraphQL schema
For the complete list of supported types, visit the [https://backstage.io/docs/features/software-catalog/descriptor-format#spectype-required-2 Backstage docs].
|-
| <code>spec.lifecycle</code>
<small>required | string</small>
| To do: Add these
|-
| <code>spec.owner</code>
<small>required | string</small>
| To do: Figure this out
|-
| <code>spec.definition.$text</code>
<small>required | string</small>
| 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 [https://gitlab.wikimedia.org/addshore/backstage/-/tree/main/data/apis data/apis directory].
 
== Frequently asked questions ==
 
== 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"