This adds problem objects in accordance with API specs across 5 endpoints.
looks good!
Poorly placed comment, i meant this and the one below on line 86
Maybe a way to combine these 2 statements? Since these 2 Problem objects are identical
Do we want to open new MR's in https://gitlab.wikimedia.org/repos/generated-data-platform/aqs/pageviews ?
Looking at the Backstage docs and at the Spotify Backstage demo videos, it looks like these team names under owners
should be machine-readable keys rather than names. This change swaps to using lowercase letters and dashes to match the style used for API names.
Looking at the Backstage docs and at the Spotify Backstage demo videos, it looks like these team names under owners
should be machine-readable keys rather than names. This change swaps to using lowercase letters and dashes to match the style used for API names.
Nikki Nikkhoui (6588eafd) at 21 Dec 22:39
Nikki Nikkhoui (beba5e7d) at 21 Dec 22:39
Merge branch 'update-sync-script' into 'main'
... and 2 more commits
Nikki Nikkhoui (6588eafd) at 21 Dec 21:47
update prod config catalog all.yaml url
Nikki Nikkhoui (51267ef9) at 21 Dec 21:46
sync script should point to correct directory
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.
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:
This PR makes some decisions about how we use various API properties. I’d love to get feedback on how these could be better.
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.
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”:
These are all rough guesses based on my knowledge, so I’d appreciate some suggestions, especially around those APIs classified as system: services
.
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:
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”:
The tags in this PR really are just guesses on my part. Suggestions wanted!
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
In order for this to work locally, copy the changes from api-config.production.yaml to your local config file: app-config.yaml
Nikki Nikkhoui (4ffc7457) at 21 Dec 19:09
Merge branch 'add-apis' into 'main'
... and 4 more commits