-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathopenapi.yaml
372 lines (341 loc) · 15.8 KB
/
openapi.yaml
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
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
openapi: 3.1.0
info:
title: ProbeLab API
summary: ProbeLab API for awesome metrics 💫
description: |
The ProbeLab API offers endpoints for retrieving detailed network
metrics.
This API loosely follows the [Google JSON Style Guide](https://google.github.io/styleguide/jsoncstyleguide.xml).
This means, all successful responses will only have a `data` field
containing the payload. All error responses will only have an `error` field
containing at least a `message` field with an error description. Following
the style guide, if there are multiple errors the `error` object will
contain another `errors` array.
version: 0.3.0
contact:
name: ProbeLab Team
url: https://probelab.io
email: [email protected]
servers:
- url: 'https://api.probelab.io'
description: Production
security:
- ApiKeyAuth: []
paths:
/v1/projects/celestia/networks/{network}/stats/{statistic}:
get:
tags:
- Celestia
summary: Get Aggregate Statistics
description: |
This endpoint returns statistics about the given Celestia network. Check
the different path and query parameter documentation below. The maximum
number of data points that this endpoint returns is `512`. The number of
data points is derived by dividing the `start` and `end` time range
by the `interval` duration. This is an arbitrary limitation and if
you need different limits, let us know.
This default data points granularity is 1h and the minimum is 10 minutes.
operationId: getNetworkStats
parameters:
- in: header
name: X-Request-ID
description: |
When you provide the `X-Request-ID` header and encounter an issue
with the API we will be better able to identify the cause.
schema:
type: string
format: uuid
- $ref: '#/components/parameters/celestiaNetwork'
- name: statistic
in: path
description: |
The aggregation of interest.
In the future we plan to support:
- `protocol` - The `columns` field in the response will protocol strings like `/ipfs/id/1.0.0` or `/celestia/header-ex/v0.0.3`
- `datacenter` - The `columns` field in the response will contain names of datacenters that peers are hosted in like `Amazon`.
- `isDatacenter` - The `columns` field in the response will just contain `true` or `false`.
We don't give a guarantee for the above. Especially `protocol` seems of low interest so we might drop that.
required: true
schema:
$ref: '#/components/schemas/CelestiaStatistics'
- name: start
in: query
description: |
The UTC aggregation start timestamp. In combination with the `end`
query parameter, this endpoint will only return the aggregation of
peers that were seen in the network within the time range spanned by
both timestamps.
If this query parameter is not provided the API will return all peers
that were seen up until 24h before the `end` timestamp (which is set
to `now` by default).
Note that the timestamp will be rounded down to the nearest multiple
of `interval` which is set to 3600 seconds (1h).
You can provide timestamps as defined by [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)
in the format `2006-01-02T15:04:05+07:00`. You can omit the timezone
part `2006-01-02T15:04:05Z` (the `Z` suffix indicates UTC).
example: "2024-11-05T10:04:30Z"
schema:
type: string
format: date-time
- name: end
in: query
description: |
The UTC aggregation end timestamp. By default this is set to the current
time.
Note that the timestamp will be rounded down to the nearest multiple
of `interval` which is set to 3600 seconds (1h).
You can provide timestamps as defined by [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)
in the format `2006-01-02T15:04:05+07:00`. You can omit the timezone
part `2006-01-02T15:04:05Z` (the `Z` suffix indicates UTC).
schema:
type: string
format: date-time
example: "2024-11-05T10:04:30Z"
- name: interval
in: query
description: |
The aggregation interval in seconds. By default this is set to 3600
(1h).
The `start` and `end` times will be rounded down to a multiple of
`interval` (since the beginning of the unix epoch).
For example, the a start or end timestamp of `2024-12-07T12:15:36`
with an interval of `1h` will be truncated to `2024-12-07T12:00:00`.
Further, the time range spanned by start and end will be divided
into `interval`-sized chunks in which the aggregation happens.
The value needs to be a multiple of the minimum interval size of
600 seconds (10 minutes).
schema:
type: integer
minimum: 600
default: 3600
example: "86400"
- name: nodetypes
in: query
description: |
A comma separated list of node types to filter the results by. The
results will only contain nodes with any of the given type. The
maximum number of node types you can define here is five.
If no node types are specified, no filtering takes place and all
types will be returned.
schema:
type: array
items:
type: string
example: "bridge,light"
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
start:
type: string
format: date-time
description: |
The start time used for the aggregation. This can differ
from the provided start time. As indicated above, the
given timestamp is rounded down to the nearest multiple
of `interval`. Then, if the `start` timestamp is after
the `end` timestamp, we exchange both values. This
timestamp also may not match the first timestamp in
the `index` array. This can happen if we don't have
data points for such an early time. It just indicates
the start of the search space.
end:
type: string
format: date-time
description: |
The end time used for the aggregation. This can differ
from the provided end time. As indicated above, the
given timestamp is rounded down to the nearest multiple
of `interval`. Then, if the `end` timestamp is before
the `start` timestamp, we exchange both values. This
timestamp also never matches the last timestamp in
the `index` array. The last timestamp in the array
corresponds to the last bucket of the aggregation until
the `end` time. Therefore, the last timestamp in the
list is usually `interval` seconds earlier than this
`end` timestamp. If the `end` timestamp is in the
future the difference of the last timestamp in the
index array and this `end` value is larger accordingly.
It just indicates the end of the search space.
interval:
type: integer
description: |
The used aggregation interval in seconds.
project:
type: string
description: |
Mirroring back the project that was aggregated.
network:
type: string
description: |
Mirroring back the network that was aggregated.
statistic:
$ref: '#/components/schemas/CelestiaStatistics'
description: |
Mirroring back the statistic that the data represents.
index:
type: array
items:
type: string
description: |
Depending on the aggregation this is index for the data.
When plotting the data, this commonly will contain
x-axis values. In the case of the `nodetype` and `version`
statistics this will contain timestamp strings in the
[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)
format with seconds precision.
columns:
type: array
items:
type: string
description: |
For each index entry we can have multiple values that
correspond to that index. In the case of the `nodetype`
statistic we can have values for multiple node types
at each timestamp. This `columns` array will contain
an ordered list of node types. The ordering corresponds
to the values array of arrays below.
In the case of the `version` statistic this array will
contain a lexicographically sorted list of valid semver
strings.
In the case of the `country` statistic this array will
contain [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1)
alpha-2 codes like `US`, `GR`, or `FR`. There are two
special cases that will also appear in this array
which are `unknown` and `multi`. The former means that
we were not able to map a certain peer to a country
and the latter means that we saw a peer connecting from
multiple countries.
In the case of the `city` statistic this array will
contain geohash+city name combinations formatted like
`$geo_hash,$city_name`. Note that there can be
multiple different geo hashes for the same city name.
There are two special cases as in the `country`
statistic. This array may also contain entries that
correspond to unknown and multiple locations of peers.
These will appear in the resulting array as
`s00000000,multi` and `s00000000,unknown`
respectively. `s00000000` corresponds to the lat/long
values of `0`, `0`.
values:
type: array
items:
type: array
items:
type: number
description: |
An array of arrays. Each item in the top level array
corresponds to a single index and each item in the
nested array to a column.
examples:
- data:
start: "2024-12-05T00:00:00"
end: "2024-12-05T02:00:00"
interval: 3600
statistic: "nodetype"
project: "celestia"
network: "mainnet"
index:
- "2024-12-05T00:00:00"
- "2024-12-05T01:00:00"
columns:
- "bridge"
- "full"
- "light"
- "other"
values:
- [ 124, 17, 229, 33]
- [ 123, 17, 229, 33]
- data:
start: "2024-12-05T00:00:00"
end: "2024-12-05T02:00:00"
interval: 3600
statistic: "version"
project: "celestia"
network: "mainnet"
index:
- "2024-12-05T00:00:00"
- "2024-12-05T01:00:00"
columns:
- "0.17.1"
- "0.20.0"
values:
- [ 124, 17]
- [ 123, 17]
- data:
start: "2024-12-05T00:00:00"
end: "2024-12-05T02:00:00"
interval: 3600
statistic: "country"
project: "celestia"
network: "mainnet"
index:
- "2024-12-05T00:00:00"
- "2024-12-05T01:00:00"
columns:
- "FR"
- "ES"
values:
- [ 124, 17]
- [ 123, 17]
- data:
start: "2024-12-05T00:00:00"
end: "2024-12-05T02:00:00"
interval: 3600
statistic: "city"
project: "celestia"
network: "mainnet"
index:
- "2024-12-05T00:00:00"
- "2024-12-05T01:00:00"
columns:
- "69y7hj5ttkde,Caseros"
- "6e9dch78y512,Salta"
values:
- [ 124, 17]
- [ 123, 17]
'400':
description: Bad Request
$ref: '#/components/responses/ErrorResponse'
'401':
description: Unauthorized
$ref: '#/components/responses/ErrorResponse'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: ProbeLab-API-Key
parameters:
celestiaNetwork:
name: network
in: path
description: The network of interest. Arabica and Mocha are not supported yet.
required: true
schema:
type: string
enum: [mainnet]
schemas:
CelestiaStatistics:
type: string
enum: [nodetype, version, country, city]
responses:
ErrorResponse:
description: A generic error response.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string