Add metadata for Vector's API

[binarylogic]

We should add metadata for Vector's new GraphQL API. This will allow us to generate docs and include it in our reference documentation.

• Endpoints
• Health endpoint and how it's used for healtchecks
• GraphQL schema?

[leebenson]

To add some context to this, GraphQL APIs are 'self-documenting' -- the schema is fully typed, providing known inputs/outputs for every query type. This can be augmented with doc comments that become part of the public API.

By default, this schema is available to all GraphQL clients, that can fire off an introspection query to get at it. Incidentally, this is what we do in both vector-ui and as of #3778, in Vector too. Types/clients are generated entirely off the back of schema introspection.

For Vector users, this is accessible in a more friendly way via the playground that will (by default) run on http://localhost:8686/playground, and shows up in a sidebar like this:

No doubt we'll want to extract that documentation, and make it navigatable as part of public Vector docs, so this can be acknowledged by prospective users even before firing up Vector. There's likely some tooling to make the schema easier to navigate. There's also the option of setting up a sandboxed environment with dummy data, and providing a hosted version of the playground, similar to Github's own -- that'd be a neat, low-friction way to assess the power of direct Vector observability.

We could also implement a build step / CLI command for updating the docs based on the current live schema.

A few different ways we could go with this. It being a typed schema should aid it, in any case.

[leebenson]

@binarylogic - could you clarify kind of metadata you're wanting here please?

I'll move this to the backlog for now. Feel free to move it back into the sprint if this is something that needs addressing soon.

[binarylogic]

Anything required for the reference docs. Such as queries, mutations, and so on. If we would prefer to lean on the explorer, then we can defer to that. I still think there is value in having explicit reference docs we can link to though.

[leebenson]

I think there's three ways we could go:

Static docs

There are a few generators listed at https://nordicapis.com/graphql-documentation-generators-explorers-and-tools/ we could leverage, depending on what we like the look of.

An example is graphdoc, which would wind up looking something like this.

Pros:

• Can use the schema.json as the canonical source
• Complete view of the schema

Cons:

• An extra tool to generate the source
• Would need to figure out how it integrates with our existing front-end UI (or, could be separate)
• Varying degrees of design control
• Not clear if we can add custom data, such as sample queries and our usual hand-holding

Live playground

We could host a real Vector instance + GraphQL Playground, which would include the introspected docs, have sample queries that could be executed, and responses coming back from the server.

The same experience as using http://localhost:8686/playground on a locally running Vector instance, but with our own curated dummy data.

Pros:

• Interaction/fun. Users can play with it immediately
• They get to try out live queries and see the results
• Nice schema/document explorer; automatically in sync
• Possible to add sample queries; instant gratification

Cons:

• Separate infrastructure to maintain
• Need to curate demo topology to throw some meaningful results back
• Open/public- issues we can currently kick down the road, like query complexity / request limiting, might come to the fore
• No built-in UI for our own content -- just the playground, as-is

Regular docs, automated with 'try this query'

A hybrid approach: Regular content hosted in our own UI, with some concept of 'execute this query, live' -- a button, or other action that allows results to be seen in-view, or via an external playground.

Github does this: https://developer.github.com/v4/guides/using-the-explorer/

(In GH's case, they send the user to a GraphQL Playground.)

Since we control the UI, one option would be to embed a GraphQL client directly in it, so results could be shown in a design layout that we can control.

Pros:

• Most flexible
• Content and interaction with the API are both under our control -- we don't even have to send the user off-site
• Interactive/engaging

Cons:

• Extra complexity in the UI -- with a GraphQL client, etc
• Still have to maintain our own live Vector instance, if we want interactive queries

CC'ing @sghall - he might have some thoughts on the above.

[binarylogic]

A separate docs site just for the GraphQL API is a non-starter. If we go that route I would rather figure out a way to add that data to our Cue files and use the docs site we already have. Is there any reason we couldn't do that? I don't know that we need a hosted eplorer just yet.

[leebenson]

Worth @sghall weighing in. I don't have much context with either cue, or how the current docs are generated. One of GraphQL's touted features is self-documentation; hopefully we can avoid maintaining separate cue files.

cuelang graphql doesn't Google well.

[binarylogic]

Right, but you'll need to get context and help with documentation. It's why we assigned you #4368 and #4347. The bottom line is:

1. We need hosted documentation for our API somewhere. This should include written documentation that describes the feature as well as reference docs that we can link to.
2. We should care about the UX and not send the user to different documentation sites unless it is better for the UX. I don't care if it's harder for us internally.

[leebenson]

Part of it is definitely just not being familiar with cue syntax, but I think the bigger part is knowing what we want from the experience. Many GraphQL APIs are interactive and tied to a playground. If I went ahead and built a static cue-based reference and then we realise we want some way to interact with the GraphQL API, it could all be for nought.

There's also apparently zero references of anyone that I could find from a superficial search, mapping GraphQL schema -> cue. What I did find were a couple of issues that seemed to suggest cue changes to accommodate a more GraphQL-like schema: cuelang/cue#339, cuelang/cue#69.

Again, I don't have a ton of context at this stage, so I will look more specifically at cue jumping to any conclusions. But I thought it was worth prompting what we're hoping to get out of documentation first to get some idea of a starting point.

Knowing we don't want a playground or a way to execute live queries is good background to have.

[lucperkins]

@binarylogic @leebenson If we have the resources to create GraphQL doc templates and generate the reference docs within our current setup, that's the way to go. I do think, however, that it'd be best to use schema.json as the source of truth rather than Cue. That file is already generated from code and I think that the Cue layer would not just be unnecessary but also add a layer at which difficult-to-track-down discrepancies are bound to arise (because schema.json and the Cue code definitions would need to be manually synced). So to me the ideal is: Rust code --> schema.json --> Gatsby.

If we don't have the resources to create our own GraphQL doc templates, then we can add a docs build step that uses one of the many generators to build the HTML under vector.dev and not in a separate site per se. The look and feel would be separate—although I think that some customization may be possible—but it's worth bearing in mind that many docs portals do have separate, non-integrated REST/GraphQL docs, so that may not be too discordant with reader expectations.

[leebenson]

I do think, however, that it'd be best to use schema.json as the source of truth rather than Cue. That file is already generated from code and I think that the Cue layer would not just be unnecessary but also add a layer at which difficult-to-track-down discrepancies are bound to arise (because schema.json and the Cue code definitions would need to be manually synced). So to me the ideal is: Rust code --> schema.json --> Gatsby.

Agreed. This is what struck me as odd. We already have a full schema.json, and many examples of GraphQL being self-documenting (the GraphQL playground, docs sites generation, the GraphQL API explorer), so it seem(ed) redundant to essentially recreate the canonical source.

But I don't know enough about cue to conclude that. There may well have been an existing gql -> cue generator, but I can't see anything obvious.

If we don't have the resources to create our own GraphQL doc templates, then we can add a docs build step that uses one of the many generators to build the HTML under vector.dev and not in a separate site per se.

Agreed. FWIW @binarylogic, I wasn't advocating for external docs. Just pointing out the existing generators.

I also think @sghall might want to chime in with some thoughts, since he's worked extensively on both the docs and GraphQL in the front-end in general, and may have some ideas for how we can leverage the existing toolchain to make for a better UX. It's very possible to build something in-house and make it interactive, even if we don't opt for a generator.