Add initial GraphQL documentation

6 files changed, 249 insertions, 2 deletions

diff --git a/git.sr.ht/api.md b/git.sr.ht/api.md
index f8c2233..c542054 100644
--- a/git.sr.ht/api.md
+++ b/git.sr.ht/api.md
@@ -2,6 +2,9 @@
 title: git.sr.ht API reference
 ---
 
+**NOTICE**: This is the documentation for the legacy REST API. It is being
+replaced with the [GraphQL API](graphql.md).
+
 The git.sr.ht API allows you to browse, create, and manage repositories on
 git.sr.ht programmatically. This API follows the [standard sourcehut API
 conventions](/api-conventions.md).
diff --git a/git.sr.ht/graphql.md b/git.sr.ht/graphql.md
new file mode 100644
index 0000000..3d43cb2
--- /dev/null
+++ b/git.sr.ht/graphql.md
@@ -0,0 +1,14 @@
+---
+title: git.sr.ht's GraphQL API
+toc: false
+---
+
+**NOTICE**: This is the documentation for git.sr.ht's new GraphQL API. For
+information on the legacy REST API, see [api.md](api.md).
+
+git.sr.ht's GraphQL API is compatible with the standard [SourceHut GraphQL API
+conventions](/graphql.md).
+
+See also:
+
+- [git.sr.ht GraphQL playground](https://git.sr.ht/graphql)
diff --git a/graphql.md b/graphql.md
new file mode 100644
index 0000000..064fe6c
--- /dev/null
+++ b/graphql.md
@@ -0,0 +1,212 @@
+---
+title: GraphQL on SourceHut
+---
+
+SourceHut offers a number of APIs via [GraphQL](https://graphql.org). This page
+documents the traits common to all of our GraphQL APIs.
+
+**NOTICE**: GraphQL support is a work-in-progress. Its completion is a key
+priority for the SourceHut beta. If you're looking for documentation related to
+our legacy APIs, which have broader coverage among our services, see [API
+conventions](api-conventions.md).
+
+## List of GraphQL APIs
+
+*This list will be expanded as GraphQL is rolled out for more services.*
+
+- [meta.sr.ht](/meta.sr.ht/graphql.md)
+- [git.sr.ht](/git.sr.ht/graphql.md)
+
+## GraphQL playground
+
+Each service provides a "playground" where you can run GraphQL queries to test
+and learn about the system. The canonical reference for each GraphQL schema is
+also available in the playground.
+
+**NOTICE**: The GraphQL playgrounds are wired up to your *production* data. Any
+queries you perform will affect your real data!
+
+- [meta.sr.ht playground](https://meta.sr.ht/graphql)
+- [git.sr.ht playground](https://git.sr.ht/graphql)
+
+## Authentication strategies
+
+GraphQL authentication is based on OAuth 2.0 and is compatible with
+[RFC 6749][RFC 6749]. Detailed documentation on our OAuth 2.0 implementation is
+available in the [meta.sr.ht documentation][meta oauth].
+
+[RFC 6749]: https://tools.ietf.org/html/rfc6749
+[meta oauth]: /meta.sr.ht/oauth.md
+
+In short, there are two primary modes of authentication:
+
+- Personal access tokens
+- OAuth Bearer tokens
+
+The former is suited to users who are writing their own scripts, CLI programs
+with no web component, and so on. Personal access tokens are available from
+[meta.sr.ht/oauth2](https://meta.sr.ht/oauth2).
+
+The latter is useful for third-parties who wish to provide a streamlined
+authentication process. You should first register for an OAuth 2.0 client at
+[meta.sr.ht/oauth2](https://meta.sr.ht/oauth2). For details, consult [RFC
+6749][RFC 6749] and the [meta.sr.ht documentation][meta oauth].
+
+In either case, once a token is obtained, it is used by setting the
+`Authentication` header to `Bearer <token>`, e.g.
+`Authentication: Bearer AI+ym2EAAAAAAAAIc2lyY21wd26a8JLR48pyNs2ImxWYjgi9YVGxssyt5qk4YyV7BhHXAg`
+
+### Access scopes
+
+It is possible (and strongly encouraged) for the user to limit the scope of
+access that is provided by an authentication token. The access scopes supported
+by each service, and the required scopes to utilize each resolver, are
+documented in that service's GraphQL schema.
+
+## Performing GraphQL Queries
+
+All of our GraphQL services accept queries at `/query`. To perform your query,
+submit a JSON payload to this endpoint as an HTTP POST request with the
+following schema:
+
+```json
+{
+    "query": "your GraphQL query...",
+    "variables": {
+        "foo": "bar"
+    }
+}
+```
+
+The `variables` field is optional, if your query requires no variables. A simple
+query which is supported on all APIs is:
+
+```json
+{
+    "query": "version { major, minor, patch }"
+}
+```
+
+Your request shall have the `Content-Type` set to `application/json`.
+
+### Requesting with cURL
+
+Here is a simple request:
+
+```sh
+oauth_token=your oauth token
+curl \
+  --oauth2-bearer="$oauth_token" \
+  -H 'Content-Type: application/json' \
+  -d '{"query": "version { major, minor, patch }"}' \
+  https://meta.sr.ht/query
+```
+
+Obtain a personal access token from
+[meta.sr.ht/oauth2](https://meta.sr.ht/oauth2). See [Authentication
+strategies](#authentication-strategies) for details.
+
+### Uploading files
+
+Some GraphQL resolvers accept file uploads, via the `Upload` type. Our
+implementation is compatible with the [GraphQL multipart request
+specification](https://github.com/jaydenseric/graphql-multipart-request-spec).
+
+## Query complexity limits
+
+To limit abuse, we calculate the complexity of your query before executing it,
+and apply an upper limit. As a general rule of thumb, the complexity is
+a function of how many resoruces your request implicates. For example, consider
+the following (silly) query:
+
+```
+query {
+  me {
+    sshKeys {
+      results {
+        user {
+          sshKeys {
+            results {
+              user { 
+                canonicalName
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Each field adds 1 to your complexity, unless it represents a relationship like
+sshKeys - in which case it is multipled by the number of results you request.
+The total complexity of your request is capped to 200 by default; some services
+permit more.
+
+Additionally, the total time spent processing your request is capped to 3
+seconds by default, however, more time is permitted for file uploads.
+
+### Cursors
+
+The number of results returned from a cursored resolver is limited to a certain
+cap, and is used to spread your work out over several requests. Consider this
+example:
+
+```
+query {
+  me {
+    sshKeys {
+      cursor
+      results {
+        fingerprint
+      }
+    }
+  }
+}
+```
+
+The `cursor` field returns an opaque string which can be used to return
+additional results, or `null` if there are none. The following request reutrns
+another page:
+
+```
+query {
+  me {
+    sshKeys(cursor: $cursor) {
+      cursor
+      results {
+        fingerprint
+      }
+    }
+  }
+}
+```
+
+You may perform repeated GraphQL queries to obtain all results. The default
+limit for results returned from a single request is 25. Some resolvers accept a
+`Filter` parameter which allows you to request a different number of results
+&mdash; be aware of the complexity limits while tuning this number.
+
+## API stability guarantees
+
+The `version` resolver provides API versioning information which is compatible
+with [semantic versioning](https://semver.org). The *major* version increments
+when the API is changed in a backwards-incompatible way; *minor* when new
+features are added, and *patch* when bugs are fixed. Changes presumed to be
+backwards-compatible include:
+
+- Adding new types
+- Adding new resolvers
+- Adding new fields to existing types
+- Adding new members to enums
+
+The special version `0.0.0` indicates an API which is still undergoing its
+initial design work, and provides no stability guarantees whatosever.
+
+Two additional fields are provided by the `version` resolver: `deprecationDate`
+and `features`. The former, if not null, indicates the date at which a major
+version increment is planned. Interested parties may want to monitor this value
+and incorporate it into their planning. The latter, which is not available for
+all APIs, enumerates the status of optional features applicable to this
+SourceHut installation.
diff --git a/index.html b/index.html
index aa3e1be..0e7b40b 100644
--- a/index.html
+++ b/index.html
@@ -93,7 +93,7 @@ dt {
     <dd>
       <a href="/git.sr.ht">User Manual</a>
       &mdash;
-      <a href="/git.sr.ht/api.md">API Reference</a>
+      <a href="/git.sr.ht/graphql.md">API Reference</a>
     </dd>
   </div>
   <div class="col-md-4">
@@ -149,7 +149,7 @@ dt {
     <dd>
       <a href="/meta.sr.ht">User Manual</a>
       &mdash;
-      <a href="/meta.sr.ht/api.md">API Reference</a>
+      <a href="/meta.sr.ht/graphql.md">API Reference</a>
     </dd>
   </div>
 </dl>
diff --git a/meta.sr.ht/api.md b/meta.sr.ht/api.md
index e07c21c..c1255ec 100644
--- a/meta.sr.ht/api.md
+++ b/meta.sr.ht/api.md
@@ -1,7 +1,11 @@
 ---
 title: meta.sr.ht API
+toc: false
 ---
 
+**NOTICE**: This is the documentation for the legacy REST API. It is being
+replaced with the [GraphQL API](graphql.md).
+
 There are two primary APIs for accessing meta.sr.ht programmatically:
 
 - [OAuth API](oauth-api.md): authenticating across all sr.ht services
diff --git a/meta.sr.ht/graphql.md b/meta.sr.ht/graphql.md
new file mode 100644
index 0000000..3af0202
--- /dev/null
+++ b/meta.sr.ht/graphql.md
@@ -0,0 +1,14 @@
+---
+title: meta.sr.ht's GraphQL API
+toc: false
+---
+
+**NOTICE**: This is the documentation for meta.sr.ht's new GraphQL API. For
+information on the legacy REST API, see [api.md](api.md).
+
+meta.sr.ht's GraphQL API is compatible with the standard [SourceHut GraphQL API
+conventions](/graphql.md).
+
+See also:
+
+- [meta.sr.ht GraphQL playground](https://meta.sr.ht/graphql)