gdatum/api/spec.yaml at master · EpicStep/gdatum · GitHub

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
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
openapi: 3.0.2
info:
  version: 1.0.0
  title: Gdatum API
  description: Query game-server metadata, live player counts, and historical activity across supported multiplayer platforms.
servers:
  - url: https://gdatum.epicstep.dev/api
    description: Production
  - url: 127.0.0.1:8080/api
    description: Local development
tags:
  - name: monitoring
    description: Endpoints for monitoring game servers and their player activity.
paths:
  /multiplayers/summaries:
    get:
      tags:
        - monitoring
      summary: List player-count summaries for every multiplayer platform
      operationId: listMultiplayerSummaries
      parameters:
        - name: playersOrderAsc
          in: query
          description: If true, sort platforms by current player count in ascending order. Defaults to descending.
          schema:
            type: boolean
      responses:
        '200':
          $ref: "#/components/responses/ListMultiplayerSummariesOK"
  '/multiplayer/{multiplayerName}/servers':
    get:
      tags:
        - monitoring
      summary: List servers for a multiplayer platform
      operationId: listServerSummaries
      parameters:
        - name: multiplayerName
          in: path
          description: Identifier of the multiplayer platform (for example, `ragemp` or `magestic`).
          required: true
          schema:
            type: string
        - name: playersOrderAsc
          in: query
          description: If true, sort servers by current player count in ascending order. Defaults to descending.
          schema:
            type: boolean
        - name: limit
          in: query
          description: Maximum number of servers to return. Used together with `offset` for pagination.
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 100
        - name: offset
          in: query
          description: Number of servers to skip from the start of the result set. Used together with `limit` for pagination.
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 0
        - name: includeOffline
          in: query
          description: If true, include servers that are currently offline in the response. Defaults to false.
          schema:
            type: boolean
      responses:
        '200':
          $ref: "#/components/responses/ListServerSummariesOK"
        '404':
          description: The requested multiplayer platform is not supported.
  '/multiplayer/{multiplayerName}/server/{serverHost}':
    get:
      tags:
        - monitoring
      summary: Get a server by its host
      operationId: getServer
      parameters:
        - name: multiplayerName
          in: path
          description: Identifier of the multiplayer platform (for example, `ragemp` or `magestic`).
          required: true
          schema:
            type: string
        - name: serverHost
          in: path
          description: Host of the server in `address:port` format.
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: "#/components/responses/GetServerOK"
        '404':
          description: No server with the given host was found on this platform.
  '/multiplayer/{multiplayerName}/server/{serverHost}/statistics':
    get:
      tags:
        - monitoring
      summary: Get historical player-count statistics for a server
      operationId: listServerStatistics
      parameters:
        - name: multiplayerName
          in: path
          description: Identifier of the multiplayer platform (for example, `ragemp` or `magestic`).
          required: true
          schema:
            type: string
        - name: serverHost
          in: path
          description: Host of the server in `address:port` format.
          required: true
          schema:
            type: string
        - name: from
          in: query
          description: Inclusive start of the time range to query.
          required: true
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: Inclusive end of the time range to query.
          required: true
          schema:
            type: string
            format: date-time
        - name: precision
          in: query
          description: Granularity at which data points are aggregated.
          schema:
            type: string
            default: perHour
            enum:
              - perHour
              - perDay
      responses:
        '200':
          $ref: "#/components/responses/ListServerStatisticsOK"
        '404':
          description: No server with the given host was found on this platform.
components:
  responses:
    ListMultiplayerSummariesOK:
      description: Player-count summaries for every supported multiplayer platform.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/MultiplayerSummary"
    ListServerSummariesOK:
      description: Servers belonging to the requested multiplayer platform.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/ServerSummary"
    GetServerOK:
      description: Detailed information about the requested server.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DetailedServer"
    ListServerStatisticsOK:
      description: Time-series player-count statistics for the requested server.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/ServerStatisticPoint"
  schemas:
    MultiplayerSummary:
      type: object
      description: Aggregate player activity for a single multiplayer platform.
      required:
        - name
        - playersCount
      properties:
        name:
          type: string
          description: Identifier of the multiplayer platform.
        playersCount:
          type: integer
          format: int64
          description: Total number of players currently connected across all servers on the platform.
    ServerSummary:
      type: object
      description: Lightweight representation of a server, suitable for list views.
      required:
        - host
        - name
        - playersCount
      properties:
        host:
          type: string
          description: Host of the server in `address:port` format.
        name:
          type: string
          description: Display name of the server.
        playersCount:
          type: integer
          format: int32
          description: Number of players currently connected to the server.
    DetailedServer:
      type: object
      description: Detailed information about a single server.
      required:
        - name
      properties:
        name:
          type: string
          description: Display name of the server.
        url:
          type: string
          description: Public URL advertised by the server, if any.
        gamemode:
          type: string
          description: Game mode reported by the server.
        language:
          type: string
          description: Primary language reported by the server.
        playersCount:
          type: integer
          format: int64
          description: Number of players currently connected to the server.
        collectedAt:
          type: string
          format: date-time
          description: Time at which this snapshot was collected.
    ServerStatisticPoint:
      type: object
      description: A single data point in a server's historical player-count series.
      required:
        - collectedAt
        - playersCount
      properties:
        collectedAt:
          type: string
          format: date-time
          description: Time at which this measurement was collected.
        playersCount:
          type: integer
          format: int32
          description: Number of players connected to the server at `collectedAt`.