Skip to content

Commit d7a9697

Browse files
pklaschkapklaschka
committed
feat(docs/develop): 🚧 Add GraphQL Base Schema Reference (WIP!)
As soon as possible, we should download the Schema from the server repository.
1 parent 1b5f2a1 commit d7a9697

File tree

5 files changed

+367
-3
lines changed

5 files changed

+367
-3
lines changed

‎develop/references/graphql-base-schema.md

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
---
2+
title: GraphQL Base Schema
3+
description:
4+
The base GraphQL schema that all Server State Servers have to comply with
5+
sidebar_position: 1
6+
---
7+
8+
Server State makes heavy use of an extensible GraphQL API.
9+
10+
While the complete schema depends on the extensions installed by the user, the
11+
following schema provides the base for every such schema. It can, thus, be
12+
trusted to exist during plugin/extension development.
13+
14+
_Generated using
15+
[`graphql-markdown`](https://github.com/exogen/graphql-markdown)_
16+
17+
<!-- Auto-generated! -->
18+
19+
<!-- START graphql-markdown -->
20+
21+
## Query
22+
23+
<table>
24+
<thead>
25+
<tr>
26+
<th align="left">Field</th>
27+
<th align="right">Argument</th>
28+
<th align="left">Type</th>
29+
<th align="left">Description</th>
30+
</tr>
31+
</thead>
32+
<tbody>
33+
<tr>
34+
<td colspan="2" valign="top"><strong>serverState</strong></td>
35+
<td valign="top"><a href="#serverstate">ServerState</a>!</td>
36+
<td>
37+
38+
The APIs for inspecting the server state.
39+
40+
This is the core of the Server State ecosystem and what most plugins will
41+
interact with.
42+
43+
</td>
44+
</tr>
45+
<tr>
46+
<td colspan="2" valign="top"><strong>me</strong></td>
47+
<td valign="top"><a href="#user">User</a></td>
48+
<td>
49+
50+
The currently authenticated user, if any
51+
52+
</td>
53+
</tr>
54+
</tbody>
55+
</table>
56+
57+
## Objects
58+
59+
### ServerState
60+
61+
The ServerState type that represents every query about the server state.
62+
63+
Extensions may extend this type with a property identical to their own ID to add
64+
additional "query-able" parameters.
65+
66+
For example (with a plugin id of `ABCDEF`):
67+
68+
```graphql
69+
extend type ServerState {
70+
ABCDEF: ABCDEF_State
71+
}
72+
73+
type ABCDEF_State {
74+
randomNumber: Int
75+
}
76+
```
77+
78+
<table>
79+
<thead>
80+
<tr>
81+
<th align="left">Field</th>
82+
<th align="right">Argument</th>
83+
<th align="left">Type</th>
84+
<th align="left">Description</th>
85+
</tr>
86+
</thead>
87+
<tbody>
88+
<tr>
89+
<td colspan="2" valign="top"><strong>timestamp</strong></td>
90+
<td valign="top"><a href="#int">Int</a></td>
91+
<td>
92+
93+
The timestamp of the query's execution
94+
95+
</td>
96+
</tr>
97+
</tbody>
98+
</table>
99+
100+
### User
101+
102+
An object representing a single user
103+
104+
<table>
105+
<thead>
106+
<tr>
107+
<th align="left">Field</th>
108+
<th align="right">Argument</th>
109+
<th align="left">Type</th>
110+
<th align="left">Description</th>
111+
</tr>
112+
</thead>
113+
<tbody>
114+
<tr>
115+
<td colspan="2" valign="top"><strong>id</strong></td>
116+
<td valign="top"><a href="#id">ID</a>!</td>
117+
<td>
118+
119+
The user's unique ID
120+
121+
</td>
122+
</tr>
123+
<tr>
124+
<td colspan="2" valign="top"><strong>email</strong></td>
125+
<td valign="top"><a href="#string">String</a>!</td>
126+
<td>
127+
128+
The user's email address
129+
130+
</td>
131+
</tr>
132+
<tr>
133+
<td colspan="2" valign="top"><strong>role</strong></td>
134+
<td valign="top"><a href="#userrole">UserRole</a></td>
135+
<td>
136+
137+
The user's role within the system
138+
139+
</td>
140+
</tr>
141+
</tbody>
142+
</table>
143+
144+
## Enums
145+
146+
### UserRole
147+
148+
A user's role. This defines the user's privileges within the system.
149+
150+
<table>
151+
<thead>
152+
<th align="left">Value</th>
153+
<th align="left">Description</th>
154+
</thead>
155+
<tbody>
156+
<tr>
157+
<td valign="top"><strong>admin</strong></td>
158+
<td>
159+
160+
An admin user with additional privileges (like managing other user accounts and
161+
installing extensions)
162+
163+
</td>
164+
</tr>
165+
<tr>
166+
<td valign="top"><strong>user</strong></td>
167+
<td>
168+
169+
A "normal" user without any special privileges
170+
171+
</td>
172+
</tr>
173+
</tbody>
174+
</table>
175+
176+
## Scalars
177+
178+
### Boolean
179+
180+
The `Boolean` scalar type represents `true` or `false`.
181+
182+
### ID
183+
184+
The `ID` scalar type represents a unique identifier, often used to refetch an
185+
object or as key for a cache. The ID type appears in a JSON response as a
186+
String; however, it is not intended to be human-readable. When expected as an
187+
input type, any string (such as `"4"`) or integer (such as `4`) input value will
188+
be accepted as an ID.
189+
190+
### Int
191+
192+
The `Int` scalar type represents non-fractional signed whole numeric values. Int
193+
can represent values between -(2^31) and 2^31 - 1.
194+
195+
### JSON
196+
197+
A `JSONSerializable` value represented as its serialized JSON string.
198+
199+
### String
200+
201+
The `String` scalar type represents textual data, represented as UTF-8 character
202+
sequences. The String type is most often used by GraphQL to represent free-form
203+
human-readable text.
204+
205+
<!-- END graphql-markdown -->

‎develop/references/schema.graphql

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
type Query {
2+
"""
3+
The APIs for inspecting the server state.
4+
5+
This is the core of the Server State ecosystem and what most plugins will interact with.
6+
"""
7+
serverState: ServerState!
8+
9+
"""
10+
The currently authenticated user, if any
11+
"""
12+
me: User
13+
}
14+
15+
"""
16+
A `JSONSerializable` value represented as its serialized JSON string.
17+
"""
18+
scalar JSON
19+
20+
"""
21+
The ServerState type that represents every query about the server state.
22+
23+
Extensions may extend this type with a property identical to their own ID to add additional "query-able" parameters.
24+
25+
For example (with a plugin id of `ABCDEF`):
26+
27+
```graphql
28+
extend type ServerState {
29+
ABCDEF: ABCDEF_State
30+
}
31+
32+
type ABCDEF_State {
33+
randomNumber: Int
34+
}
35+
```
36+
"""
37+
type ServerState {
38+
"""
39+
The timestamp of the query's execution
40+
"""
41+
timestamp: Int
42+
}
43+
44+
"""
45+
An object representing a single user
46+
"""
47+
type User {
48+
"""
49+
The user's unique ID
50+
"""
51+
id: ID!
52+
"""
53+
The user's email address
54+
"""
55+
email: String!
56+
"""
57+
The user's role within the system
58+
"""
59+
role: UserRole
60+
}
61+
62+
"""
63+
A user's role. This defines the user's privileges within the system.
64+
"""
65+
enum UserRole {
66+
"""
67+
An admin user with additional privileges (like managing other user accounts and installing extensions)
68+
"""
69+
admin
70+
"""
71+
A "normal" user without any special privileges
72+
"""
73+
user
74+
}

0 commit comments

Comments
 (0)