Skip to content

Add APIs

Alex Paskulin requested to merge add-apis into main

This PR adds an initial set of 11 APIs to the catalog for the MVP. For the MVP, Nikki and I decided that it would be best to manually add these YAML files to the Backstage repo and move to YAML files in project repositories in a post-MVP iteration. The other main thing this PR does is to add the hosts for each OpenAPI spec to the production config so that Backstage can read the specs and load them into Backstage.

Screen_Shot_2021-12-13_at_11.41.37_AM

In an attempt to minimize complexity while still providing a representative set of APIs, I chose APIs that are owned by WMF and have docs that I could locate. Since our goal is to make the list of APIs discoverable and understandable for API producers, I named the APIs with names that differentiate them based on the underlying technology. The alternative would be to have names that are so similar it’s almost impossible to differentiate them (for example: “Wikimedia API” and “Wikimedia REST API”).

APIs included in this PR:

  • API gateway API (aka the collection of endpoints routed through the gateway)
  • Event streams API
  • Image suggestions API
  • Link recommendations API
  • MediaWiki action API
  • Mediawiki core REST API
  • MediaWIki ajax interface
  • ORES API
  • RESTBase API
  • Wikifeeds API
  • Recommendation API

This PR makes some decisions about how we use various API properties. I’d love to get feedback on how these could be better.

type

In Backstage, the API “type” is less about the style of API (REST, GraphQL, etc.) and more about the standard used for the docs. Therefore, in this PR, APIs of type openapi are APIs with documentation in the form of an OpenAPI spec, regardless of how the spec was created or how the API makes use of OpenAPI tools. For APIs without an OpenAPI spec, this PR assigns them to type: none, meaning that they do not use any standard, machine-readable format for their API docs. These APIs of type: none are all documented in wikitext and/or HTML. Although this feels a bit clunky, I do think it’s worth it to define conventions for this property since it is displayed prominently in Backstage.

system

Another API property that Backstage displays prominently is “system”. Ideally, these “system” values would be entities that tie in to the service catalog, but for the MVP, I think it’s best to just list them and have them be dead links instead of going down the rabbit hole of defining the whole system. In this PR, I use these values for “system”:

  • MediaWiki
  • API gateway
  • Event platform
  • RestBase
  • Machine learning
  • Services <— Help!

These are all rough guesses based on my knowledge, so I’d appreciate some suggestions, especially around those APIs classified as system: services.

owner

Similar to “system”, I think it’s ok to leave these as dead links for the MVP. These are the teams I’ve called out as owning an API in this PR:

  • Platform Engineering Team
  • Data Engineering Team
  • Growth Team
  • Machine Learning Team
  • Product Infrastructure Team
  • Research Team

lifecycle

In the Backstage docs, they use example values of experimental, production, and deprecated. While I think these are good, it doesn’t account for APIs that are in production but still considered experimental (aka they may change suddenly without notice). In this PR, I’ve used these values for “lifecycle”:

  • experimental
  • stable
  • deprecated

tags

The tags in this PR really are just guesses on my part. Suggestions wanted!

  • rest (for REST APIs. Is the Action API a REST API?)
  • ml (for things related to machine learning, although I dislike acronyms)
  • sse (something I found in the Event Streams docs and thought sounded good?)
  • gateway (had an idea to use a tag to indicate APIs that are being routed through the API gateway, but didn’t really find a way to make it work)

links

This wasn’t a part of our original example config, but I think this is a cool opportunity to link to non-reference API docs, usually on wiki. Backstage claims to support a variety of icons, but to minimize complexity, I set them all to the “docs” icon which just looks like a page.

Once we’ve agreed on how these properties should work, I’ll update the WIP docs on Wikitech

A note about running this locally

In order for this to work locally, copy the changes from api-config.production.yaml to your local config file: app-config.yaml

Edited by Alex Paskulin

Merge request reports