Add some API documentation for endusers

Here we start adding docs covering the basics of using our GraphQL API, including how to fetch all variant frequencies for a gene.

browser/help/faq/technical-details/how-do-i-query-a-batch-of-variants-do-you-have-an-api.md

@@ -2,6 +2,6 @@
 question: 'How do I query a batch of variants? Do you have an API?'
 ---
 
-We currently do not have a way to submit batch queries on the browser, but we are actively working on developing a public API for gnomAD. We currently maintain a [GraphQL](https://graphql.org) API for internal use and groups can contact us if they want permission to use this API until a more robust public solution is launched.
+The [GraphQL](https://graphql.org) API used by the browser is open to the public. Please see our [data page](/data) for details.
 
-You can also obtain information on all variants from the VCFs and Hail Tables available on our [downloads page](/downloads).
+You can also obtain information on all variants from the VCFs and Hail Tables available on our [data page](/data).

browser/src/DownloadsPage/DownloadsPage.spec.tsx → browser/src/DataPage/DataPage.spec.tsx

@@ -4,14 +4,14 @@ import 'jest-styled-components'
 import React from 'react'
 import renderer from 'react-test-renderer'
 
-import DownloadsPage from './DownloadsPage'
+import DataPage from './DataPage'
 
 import { BrowserRouter } from 'react-router-dom'
 
-test('Downloads Page has no unexpected changes', () => {
+test('Data Page has no unexpected changes', () => {
   const tree = renderer.create(
     <BrowserRouter>
-      <DownloadsPage />
+      <DataPage />
     </BrowserRouter>
   )
   expect(tree).toMatchSnapshot()

browser/src/DownloadsPage/DownloadsPage.tsx → browser/src/DataPage/DataPage.tsx

@@ -8,35 +8,19 @@ import Link from '../Link'
 import DocumentTitle from '../DocumentTitle'
 import InfoPage from '../InfoPage'
 
-import { SectionTitle, StyledParagraph } from './downloadsPageStyles'
+import { SectionTitle, StyledParagraph, CodeBlock } from './downloadsPageStyles'
 
-import DownloadsPageTableOfContents from './TableOfContents'
+import DataPageTableOfContents from './TableOfContents'
 
 // @ts-expect-error
-import styles from './DownloadsPage.module.css'
+import styles from './DataPage.module.css'
 
 import GnomadV4Downloads from './GnomadV4Downloads'
 import GnomadV3Downloads from './GnomadV3Downloads'
 import GnomadV2Downloads from './GnomadV2Downloads'
 import GnomadV2LiftoverDownloads from './GnomadV2LiftoverDownloads'
 import ExacDownloads from './ExacDownloads'
-
-const CodeBlock = styled.code`
-  display: inline-block;
-  box-sizing: border-box;
-  max-width: 100%;
-  padding: 0.5em 1em;
-  border-radius: 0.25em;
-  background: #333;
-  color: #fafafa;
-  font-family: monospace;
-  line-height: 1.6;
-  white-space: nowrap;
-
-  &::before {
-    content: '$ ';
-  }
-`
+import GraphQLDocs from './GraphQLDocs'
 
 const TextSection = styled.div`
   width: 70%;
@@ -65,25 +49,25 @@ const BottomSpacer = styled.div`
   margin-bottom: 40rem;
 `
 
-const DownloadsPage = () => {
+const DataPage = () => {
   // Load stylesheet to make smooth scroll behavior active
   const _style = styles.html
 
   return (
     <InfoPage>
-      <DocumentTitle title="Downloads" />
-      <PageHeading>Downloads</PageHeading>
+      <DocumentTitle title="Data" />
+      <PageHeading>Data</PageHeading>
 
       <TableOfContentsSection>
-        <DownloadsPageTableOfContents />
+        <DataPageTableOfContents />
       </TableOfContentsSection>
 
       <TextSection>
         <div>
           <SectionTitle id="summary" theme={{ type: 'datasets' }}>
             Summary
           </SectionTitle>
-          <p>
+          <StyledParagraph>
             gnomAD data is available for download through{' '}
             {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */}
             <ExternalLink href="https://cloud.google.com/public-datasets">
@@ -99,19 +83,15 @@ const DownloadsPage = () => {
             <ExternalLink href="https://azure.microsoft.com/en-us/services/open-datasets/">
               Azure Open Datasets
             </ExternalLink>
-            .
-          </p>
-
-          <p>
+            . We recommend using
             {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */}
-            We recommend using <ExternalLink href="https://hail.is/">Hail</ExternalLink> and our{' '}
+            <ExternalLink href="https://hail.is/">Hail</ExternalLink> and our{' '}
             {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */}
             <ExternalLink href="https://github.com/broadinstitute/gnomad_methods">
               Hail utilities for gnomAD
             </ExternalLink>{' '}
-            to work with the data.
-          </p>
-
+            to work with this data.
+          </StyledParagraph>
           <StyledParagraph>
             In addition to the files listed below,{' '}
             {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */}
@@ -122,9 +102,15 @@ const DownloadsPage = () => {
             </ExternalLink>
             .
           </StyledParagraph>
-
+          <StyledParagraph>
+            The API used by the gnomAD browser is also open to the public. In use cases involving
+            querying a relatively small number of records with low latency, using the API to request
+            records as needed may be more suitable than working with downloaded gnomAD data. If
+            you're unsure which would be better for your use case, please reach out to the browser
+            team.
+          </StyledParagraph>
+          <h2>Download Overview</h2>
           <h3>Google Cloud Public Datasets</h3>
-
           <p>
             Files can be browsed and downloaded using{' '}
             {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */}
@@ -233,10 +219,12 @@ const DownloadsPage = () => {
 
         <ExacDownloads />
 
+        <GraphQLDocs />
+
         <BottomSpacer />
       </TextSection>
     </InfoPage>
   )
 }
 
-export default DownloadsPage
+export default DataPage

browser/src/DataPage/GraphQLDocs.tsx

@@ -0,0 +1,76 @@
+import React from 'react'
+
+import { CodeBlock, SectionTitle, StyledParagraph } from './downloadsPageStyles'
+
+import styled from 'styled-components'
+
+import { ExternalLink, Tabs } from '@gnomad/ui'
+import exampleRawQuery from './exampleRawGraphQLQuery'
+import examplePythonQuery from './examplePythonGraphQLQuery'
+import exampleJSQuery from './exampleJSGraphQLQuery'
+
+const GraphQLCodeBlock = styled(CodeBlock)`
+  white-space: pre-wrap;
+
+  &::before {
+    content: none;
+  }
+`
+
+const GraphQLDocs = () => (
+  <>
+    <SectionTitle id="api">gnomAD API</SectionTitle>
+    <StyledParagraph>
+      The gnomAD browser gets its data through a{' '}
+      {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */}
+      <ExternalLink href="https://graphql.org">GraphQL</ExternalLink> API which is open to the
+      public. Access to the API is rate-limited to 10 requests per 60-second period.
+    </StyledParagraph>
+    <StyledParagraph>
+      The API can be queried programatically by making an HTTP request to{' '}
+      <a href="/api">https://gnomad.broadinstitute.org/api</a>. Please see the GraphQL documentation
+      for details on how to{' '}
+      {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */}
+      <ExternalLink href="https://graphql.org/learn/queries/">
+        construct a query
+      </ExternalLink> and{' '}
+      {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */}
+      <ExternalLink href="https://graphql.org/learn/serving-over-http/#http-methods-headers-and-body">
+        format it to send it over HTTP
+      </ExternalLink>
+      .
+    </StyledParagraph>
+    <StyledParagraph>
+      You can also use the API interactively by visiting <a href="/api">the same address</a> in your
+      browser, which is useful for experimenting with queries. That interface also allows you to
+      explore the API schema interactively.
+    </StyledParagraph>
+    <StyledParagraph>
+      The following is an annotated GraphQL query, with some small example programs for a subset of
+      that query in Python and JavaScript. This query gets similar data to the CSV export of all
+      variants for gene <a href="/gene/ENSG00000012048?dataset=gnomad_r4">BRCA1</a>.
+    </StyledParagraph>
+    {/* @ts-expect-error TS(2741) FIXME: Property 'onChange' is missing in type '{ tabs: { ... Remove this comment to see the full error message */}
+    <Tabs
+      tabs={[
+        {
+          id: 'rawQuery',
+          label: 'Raw Query',
+          render: () => <GraphQLCodeBlock>{exampleRawQuery}</GraphQLCodeBlock>,
+        },
+        {
+          id: 'pythonQuery',
+          label: 'Python',
+          render: () => <GraphQLCodeBlock>{examplePythonQuery}</GraphQLCodeBlock>,
+        },
+        {
+          id: 'jsQuery',
+          label: 'JavaScript',
+          render: () => <GraphQLCodeBlock>{exampleJSQuery}</GraphQLCodeBlock>,
+        },
+      ]}
+    />
+  </>
+)
+
+export default GraphQLDocs

browser/src/DownloadsPage/TableOfContents.tsx → browser/src/DataPage/TableOfContents.tsx

@@ -24,7 +24,7 @@ const TableOfContentsStyledItem = styled.div<{
   }
 `
 
-const DownloadsPageTableOfContents = () => {
+const DataPageTableOfContents = () => {
   const [headings, setHeadings] = useState([])
   const { activeId } = useHeadsObserver()
   const [activeSection, setActiveSection] = useState('')
@@ -118,4 +118,4 @@ const DownloadsPageTableOfContents = () => {
   )
 }
 
-export default DownloadsPageTableOfContents
+export default DataPageTableOfContents