diff options
| -rw-r--r-- | git.sr.ht/api.md | 3 | ||||
| -rw-r--r-- | git.sr.ht/graphql.md | 14 | ||||
| -rw-r--r-- | graphql.md | 212 | ||||
| -rw-r--r-- | index.html | 4 | ||||
| -rw-r--r-- | meta.sr.ht/api.md | 4 | ||||
| -rw-r--r-- | meta.sr.ht/graphql.md | 14 |
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 +— 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. @@ -93,7 +93,7 @@ dt { <dd> <a href="/git.sr.ht">User Manual</a> — - <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> — - <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) |