Include use case example(s) in GraphQL docs
Problem to solve
One of the goals of the 2020 "contribute" challenge is to make our docs "Stripe-beautiful". As discussed in &2503 (comment 326519843), one of the strengths of Stripe is their highlighting of "use cases", with what I'd call "easy wins"
At the moment, there are few working examples to demonstrate use cases for GraphQL. While one could guess at the abilities of our GraphQL implementation with the gitlab.com/-/graphql-explorer, there's no guidance, no hints on what can be done.
GraphQL is a powerful tool, as it processes custom requests on the server, thereby improving performance in two ways:
- Custom requests avoid calls to multiple APIs
- Processing on the server avoids the overhead of transmission / filtering on the client
Further details
I think we need examples in our GraphQL docs, quite possibly a list of "use cases" with links to appropriate details.
We've seen some use cases in the Contribute session on GraphQL
We have one more use case from Slack, where the following input is used to detect vulnerabilities on existing projects:
{
vulnerabilities (reportType: DEPENDENCY_SCANNING){
nodes{
description
location
project{
fullPath
}
reportType
severity
state
title
vulnerabilityPath
}
}
}
h/t @skamani , who also noted that for actual results, this must be run by a user with projects that have had valid vulnerability scans.
Proposal
Set up a list of use cases, perhaps in https://docs.gitlab.com/ee/api/graphql/ (in the gitlab repo, maybe in a new file like doc/api/graphql/use_cases/index.md)
Make those use cases "copyable" into our GraphQL explorer
Who can address the issue
Other links/references
cc @eread for your GraphQL doc expertise; however, as GraphQL is and should be a part of all groups, I think this need will eventually get distributed among the dev teams.