~sircmpwn/paste.sr.ht

ref: api paste.sr.ht/api/graph/schema.graphqls -rw-r--r-- 4.0 KiB
df35add1Drew DeVault API: Add note about leaking blobs on delete a month ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
# 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

# This used to decorate fields which are for internal use, and are not
# available to normal API users.
directive @internal on FIELD_DEFINITION

# Used to provide a human-friendly description of an access scope.
directive @scopehelp(details: String!) on ENUM_VALUE

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!
  sha: 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 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)
}

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)
}