~sircmpwn/sr.ht-docs

b29bc24d3354366d3e00e69ae3b490c528c94bfd — Drew DeVault a month ago 84b00d4
Add initial GraphQL documentation
6 files changed, 249 insertions(+), 2 deletions(-)

M git.sr.ht/api.md
A git.sr.ht/graphql.md
A graphql.md
M index.html
M meta.sr.ht/api.md
A meta.sr.ht/graphql.md
M git.sr.ht/api.md => git.sr.ht/api.md +3 -0
@@ 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).

A git.sr.ht/graphql.md => git.sr.ht/graphql.md +14 -0
@@ 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)

A graphql.md => graphql.md +212 -0
@@ 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.

M index.html => index.html +2 -2
@@ 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>

M meta.sr.ht/api.md => meta.sr.ht/api.md +4 -0
@@ 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

A meta.sr.ht/graphql.md => meta.sr.ht/graphql.md +14 -0
@@ 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)