6.6 KiB
title |
---|
GraphQL on SourceHut |
SourceHut offers a number of APIs via GraphQL. 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.
List of GraphQL APIs
This list will be expanded as GraphQL is rolled out for more services.
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!
Authentication strategies
GraphQL authentication is based on OAuth 2.0 and is compatible with RFC 6749. Detailed documentation on our OAuth 2.0 implementation is available in the meta.sr.ht documentation.
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.
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. For details, consult RFC 6749 and the meta.sr.ht documentation.
In either case, once a token is obtained, it is used by setting the
Authorization
header to Bearer <token>
, e.g.
Authorization: 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:
{
"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:
{
"query": "{ version { major, minor, patch } }"
}
Your request shall have the Content-Type
set to application/json
.
Requesting with cURL
Here is a simple request:
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. See 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.
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 resources 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 multiplied 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, though more time is permitted for resolvers handling 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 returns
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. 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
- Adding new optional parameters to existing resolvers
- Adding new optional fields to existing input types
The special version 0.0.0
indicates an API which is still undergoing its
initial design work, and provides no stability guarantees whatsoever.
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.