diff options
| -rw-r--r-- | graphql.md | 20 |
1 files changed, 10 insertions, 10 deletions
@@ -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 — 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 |