~sircmpwn/paste.sr.ht

paste.sr.ht/api/graph/schema.graphqls -rw-r--r-- 4.0 KiB
1331c017Simon Ser go generate 8 days 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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
# 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
  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 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)
}