~sircmpwn/sr.ht-docs

c6ab5f4cb7c8ffa28c653256738be98e22bfdd29 — Drew DeVault a month ago b29bc24
GraphQL: increment header level
1 files changed, 10 insertions(+), 10 deletions(-)

M graphql.md
M graphql.md => graphql.md +10 -10
@@ 10,14 10,14 @@ 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
# 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
# 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


@@ 29,7 29,7 @@ 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
# 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


@@ 56,14 56,14 @@ 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
## 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
# 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


@@ 89,7 89,7 @@ query which is supported on all APIs is:

Your request shall have the `Content-Type` set to `application/json`.

### Requesting with cURL
## Requesting with cURL

Here is a simple request:



@@ 106,13 106,13 @@ Obtain a personal access token from
[meta.sr.ht/oauth2](https://meta.sr.ht/oauth2). See [Authentication
strategies](#authentication-strategies) for details.

### Uploading files
## 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
# 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


@@ 147,7 147,7 @@ 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
## 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


@@ 188,7 188,7 @@ 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
# API stability guarantees

The `version` resolver provides API versioning information which is compatible
with [semantic versioning](https://semver.org). The *major* version increments