Document GraphQL API

[WilliamDEdwards]

Aside from the generic API (REST), GoAlert offers a GraphQL API.

In v0.33.0, API keys were "taken out of experimental state" (#3797). However, there seems to be almost no documentation around the GraphQL API / API keys.

Here's a few things I ran into trying to get started with the GraphQL API:

1. Given an API key, how does one authenticate? (Spoiler: Authorization: Bearer ...). Although the API key does look like a bearer token, the ambiguity causes confusion: Acknowledge alert API endpoint #3412 (comment)
2. Which operations exist? Solution: add a link to /api/graphql/explore which has a neat list (already documented here: Better key management for GQL API keys #4198). Someone ran into this here: How would I hit GoAlert's API to determine an on-call user's email address? #3839 (comment)
3. When creating an API key, one has to select a 'Role', which can be 'User' or 'Admin'. What does that mean? I have found that when trying to do an UpdateAlertsMutation with an API key with the 'User' role, I simply get back 'unauthorized'. And it's up to the user to figure out what that means: wrong key? Wrong header? Wrong role?
4. When creating an API key, one has to specify a 'query'. See screenshot below. But that field has no label, so no one knows it's supposed to be a query (even though strangely, the label is present in this design: Admin Ability to Create API Keys for Integration with External Systems #3007 (comment)). The 'magic' button on the right also has no tooltip and seems to do nothing on click.
   4.1. For users unfamiliar with GraphQL, it might not be clear that a fixed query may contain variables. See this question here: Admin Ability to Create API Keys for Integration with External Systems #3007 (comment)
5. I cannot for the life of me work around "wrong query for API key". A literal comparison is done here:

   goalert/apikey/middleware.go

   Line 37 in 29e4f6c

   if p.Query != rc.Query {

   , but something must be manipulated over the wire. Tried with different indentation, with/without newlines, etc. etc. Someone else ran into this here: How would I hit GoAlert's API to determine an on-call user's email address? #3839 (reply in thread). Admittedly, one can omit the query to let GoAlert default to the API key's fixed query (

   goalert/apikey/middleware.go

   Line 24 in 29e4f6c

   if rc.Query == "" {

   ), but most clients don't support that, plus I don't like clients relying on what is essentially an implementation detail (permissions error when client specifies the wrong query for the wrong API key vs the wrong query being executed because the client uses the wrong API key).