@@ 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
## List of GraphQL APIs
# List of GraphQL APIs
*This list will be expanded as GraphQL is rolled out for more services.*
## 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
## 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.
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
— 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