303 lines
8.2 KiB
GraphQL
303 lines
8.2 KiB
GraphQL
# This schema definition is available in the public domain, or under the terms
|
|
# of CC-0, at your choice.
|
|
scalar Cursor
|
|
scalar Time
|
|
scalar Upload
|
|
"""
|
|
URL from which some secondary data may be retrieved. You must provide the
|
|
same Authentication header to this address as you did to the GraphQL resolver
|
|
which provided it. The URL is not guaranteed to be consistent for an extended
|
|
length of time; applications should submit a new GraphQL query each time they
|
|
wish to access the data at the provided URL.
|
|
"""
|
|
scalar URL
|
|
|
|
"""
|
|
This is used to decorate fields which are only accessible with a personal
|
|
access token, and are not available to clients using OAuth 2.0 access tokens.
|
|
"""
|
|
directive @private on FIELD_DEFINITION
|
|
|
|
"Used to provide a human-friendly description of an access scope."
|
|
directive @scopehelp(details: String!) on ENUM_VALUE
|
|
|
|
"""
|
|
This used to decorate fields which are for internal use, and are not
|
|
available to normal API users.
|
|
"""
|
|
directive @internal on FIELD_DEFINITION
|
|
|
|
enum AccessScope {
|
|
PROFILE @scopehelp(details: "profile information")
|
|
PASTES @scopehelp(details: "pastes")
|
|
}
|
|
|
|
enum AccessKind {
|
|
RO @scopehelp(details: "read")
|
|
RW @scopehelp(details: "read and write")
|
|
}
|
|
|
|
"""
|
|
Decorates fields for which access requires a particular OAuth 2.0 scope with
|
|
read or write access. For the meta.sr.ht API, you have access to all public
|
|
information without any special permissions - user profile information,
|
|
public keys, and so on.
|
|
"""
|
|
directive @access(scope: AccessScope!, kind: AccessKind!) on FIELD_DEFINITION | ENUM_VALUE
|
|
|
|
enum Visibility {
|
|
"Visible to everyone, listed on your profile"
|
|
PUBLIC
|
|
"Visible to everyone (if they know the URL), not listed on your profile"
|
|
UNLISTED
|
|
"Not visible to anyone except those explicitly added to the access list"
|
|
PRIVATE
|
|
}
|
|
|
|
# https://semver.org
|
|
type Version {
|
|
major: Int!
|
|
minor: Int!
|
|
patch: Int!
|
|
"""
|
|
If this API version is scheduled for deprecation, this is the date on which
|
|
it will stop working; or null if this API version is not scheduled for
|
|
deprecation.
|
|
"""
|
|
deprecationDate: Time
|
|
}
|
|
|
|
interface Entity {
|
|
id: Int!
|
|
created: Time!
|
|
"""
|
|
The canonical name of this entity. For users, this is their username
|
|
prefixed with '~'. Additional entity types will be supported in the future.
|
|
"""
|
|
canonicalName: String!
|
|
|
|
pastes(cursor: Cursor): PasteCursor! @access(scope: PASTES, kind: RO)
|
|
}
|
|
|
|
type User implements Entity {
|
|
id: Int!
|
|
created: Time!
|
|
canonicalName: String!
|
|
|
|
pastes(cursor: Cursor): PasteCursor! @access(scope: PASTES, kind: RO)
|
|
|
|
username: String!
|
|
}
|
|
|
|
type Paste {
|
|
id: String!
|
|
created: Time!
|
|
visibility: Visibility!
|
|
files: [File!]!
|
|
|
|
user: Entity! @access(scope: PROFILE, kind: RO)
|
|
}
|
|
|
|
type File {
|
|
filename: String
|
|
hash: String!
|
|
contents: URL!
|
|
}
|
|
|
|
"""
|
|
A cursor for enumerating pastes
|
|
|
|
If there are additional results available, the cursor object may be passed
|
|
back into the same endpoint to retrieve another page. If the cursor is null,
|
|
there are no remaining results to return.
|
|
"""
|
|
type PasteCursor {
|
|
results: [Paste!]!
|
|
cursor: Cursor
|
|
}
|
|
|
|
type OAuthClient {
|
|
uuid: String!
|
|
}
|
|
|
|
enum WebhookEvent {
|
|
PASTE_CREATED @access(scope: PASTES, kind: RO)
|
|
PASTE_UPDATED @access(scope: PASTES, kind: RO)
|
|
PASTE_DELETED @access(scope: PASTES, kind: RO)
|
|
}
|
|
|
|
interface WebhookSubscription {
|
|
id: Int!
|
|
events: [WebhookEvent!]!
|
|
query: String!
|
|
url: String!
|
|
|
|
"""
|
|
If this webhook was registered by an authorized OAuth 2.0 client, this
|
|
field is non-null.
|
|
"""
|
|
client: OAuthClient @private
|
|
|
|
"All deliveries which have been sent to this webhook."
|
|
deliveries(cursor: Cursor): WebhookDeliveryCursor!
|
|
|
|
"Returns a sample payload for this subscription, for testing purposes"
|
|
sample(event: WebhookEvent!): String!
|
|
}
|
|
|
|
type UserWebhookSubscription implements WebhookSubscription {
|
|
id: Int!
|
|
events: [WebhookEvent!]!
|
|
query: String!
|
|
url: String!
|
|
client: OAuthClient @private
|
|
deliveries(cursor: Cursor): WebhookDeliveryCursor!
|
|
sample(event: WebhookEvent!): String!
|
|
}
|
|
|
|
type WebhookDelivery {
|
|
uuid: String!
|
|
date: Time!
|
|
event: WebhookEvent!
|
|
subscription: WebhookSubscription!
|
|
requestBody: String!
|
|
|
|
"""
|
|
These details are provided only after a response is received from the
|
|
remote server. If a response is sent whose Content-Type is not text/*, or
|
|
cannot be decoded as UTF-8, the response body will be null. It will be
|
|
truncated after 64 KiB.
|
|
"""
|
|
responseBody: String
|
|
responseHeaders: String
|
|
responseStatus: Int
|
|
}
|
|
|
|
interface WebhookPayload {
|
|
uuid: String!
|
|
event: WebhookEvent!
|
|
date: Time!
|
|
}
|
|
|
|
type PasteEvent implements WebhookPayload {
|
|
uuid: String!
|
|
event: WebhookEvent!
|
|
date: Time!
|
|
|
|
paste: Paste!
|
|
}
|
|
|
|
"""
|
|
A cursor for enumerating a list of webhook deliveries
|
|
|
|
If there are additional results available, the cursor object may be passed
|
|
back into the same endpoint to retrieve another page. If the cursor is null,
|
|
there are no remaining results to return.
|
|
"""
|
|
type WebhookDeliveryCursor {
|
|
results: [WebhookDelivery!]!
|
|
cursor: Cursor
|
|
}
|
|
|
|
"""
|
|
A cursor for enumerating a list of webhook subscriptions
|
|
|
|
If there are additional results available, the cursor object may be passed
|
|
back into the same endpoint to retrieve another page. If the cursor is null,
|
|
there are no remaining results to return.
|
|
"""
|
|
type WebhookSubscriptionCursor {
|
|
results: [WebhookSubscription!]!
|
|
cursor: Cursor
|
|
}
|
|
|
|
type Query {
|
|
"Returns API version information."
|
|
version: Version!
|
|
|
|
"Returns the authenticated user."
|
|
me: User! @access(scope: PROFILE, kind: RO)
|
|
|
|
"Returns a specific user."
|
|
user(username: String!): User @access(scope: PROFILE, kind: RO)
|
|
|
|
"Returns a list of pastes created by the authenticated user."
|
|
pastes(cursor: Cursor): PasteCursor @access(scope: PASTES, kind: RO)
|
|
|
|
"Returns a paste by its ID."
|
|
paste(id: String!): Paste @access(scope: PASTES, kind: RO)
|
|
|
|
"""
|
|
Returns a list of user webhook subscriptions. For clients
|
|
authenticated with a personal access token, this returns all webhooks
|
|
configured by all GraphQL clients for your account. For clients
|
|
authenticated with an OAuth 2.0 access token, this returns only webhooks
|
|
registered for your client.
|
|
"""
|
|
userWebhooks(cursor: Cursor): WebhookSubscriptionCursor!
|
|
|
|
"Returns details of a user webhook subscription by its ID."
|
|
userWebhook(id: Int!): WebhookSubscription
|
|
|
|
"""
|
|
Returns information about the webhook currently being processed. This is
|
|
not valid during normal queries over HTTP, and will return an error if used
|
|
outside of a webhook context.
|
|
"""
|
|
webhook: WebhookPayload!
|
|
}
|
|
|
|
input UserWebhookInput {
|
|
url: String!
|
|
events: [WebhookEvent!]!
|
|
query: String!
|
|
}
|
|
|
|
type Mutation {
|
|
"""
|
|
Creates a new paste from a list of files. The files uploaded must have a
|
|
content type of text/* and must be decodable as UTF-8.
|
|
|
|
Note that the web UI will replace CRLF with LF in uploads; the GraphQL API
|
|
does not.
|
|
"""
|
|
create(
|
|
files: [Upload!]!,
|
|
visibility: Visibility!,
|
|
): Paste! @access(scope: PASTES, kind: RW)
|
|
|
|
"Updates the visibility of a paste."
|
|
update(id: String!, visibility: Visibility!): Paste @access(scope: PASTES, kind: RW)
|
|
|
|
"Deletes a paste by its ID."
|
|
delete(id: String!): Paste @access(scope: PASTES, kind: RW)
|
|
|
|
"""
|
|
Creates a new user webhook subscription. When an event from the
|
|
provided list of events occurs, the 'query' parameter (a GraphQL query)
|
|
will be evaluated and the results will be sent to the provided URL as the
|
|
body of an HTTP POST request. The list of events must include at least one
|
|
event, and no duplicates.
|
|
|
|
This query is evaluated in the webhook context, such that query { webhook }
|
|
may be used to access details of the event which trigged the webhook. The
|
|
query may not make any mutations.
|
|
"""
|
|
createUserWebhook(config: UserWebhookInput!): WebhookSubscription!
|
|
|
|
"""
|
|
Deletes a user webhook. Any events already queued may still be
|
|
delivered after this request completes. Clients authenticated with a
|
|
personal access token may delete any webhook registered for their account,
|
|
but authorized OAuth 2.0 clients may only delete their own webhooks.
|
|
Manually deleting a webhook configured by a third-party client may cause
|
|
unexpected behavior with the third-party integration.
|
|
"""
|
|
deleteUserWebhook(id: Int!): WebhookSubscription!
|
|
|
|
"""
|
|
Deletes the authenticated user's account. Internal use only.
|
|
"""
|
|
deleteUser: Int! @internal
|
|
}
|