-
Notifications
You must be signed in to change notification settings - Fork 0
/
openapi.yaml
568 lines (514 loc) · 17.7 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
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
openapi: 3.0.2
info:
title: Fleet v2 HTTP API
version: 2.6.0
description: HTTP-based API for Fleet Protocol v2 serving for communication between the External Server and the end users.
contact:
email: jiri.strouhal@bringauto.com
license:
name: GPLv3
url: https://www.gnu.org/licenses/gpl-3.0.en.html
servers:
- url: /v2/protocol
tags:
- name: car
- name: device
- name: module
security:
- AdminAuth: []
- oAuth2AuthCode: []
paths:
/login:
get:
x-openapi-router-controller: fleetv2_http_api.impl.controllers
operationId: login
security: []
description:
"Login using keycloak. If empty device is specified, will generate a url and device code used to authenticate a device. Tries to get token if device code is specified."
tags:
- login
responses:
'200':
description: Returns either a standard keycloak token or a json used to authenticate a device.
'302':
description: Redirect to keycloak authentication.
'500':
description: Login failed due to internal server error.
parameters:
- $ref: '#/components/parameters/Device'
/token_get:
get:
x-openapi-router-controller: fleetv2_http_api.impl.controllers
operationId: token_get
security: []
description:
"Callback endpoint for keycloak to receive jwt token."
tags:
- login
responses:
'200':
description: Returns a standard keycloak token.
'500':
description: Login failed due to internal server error.
parameters:
- $ref: '#/components/parameters/kcState'
- $ref: '#/components/parameters/kcSessionState'
- $ref: '#/components/parameters/kcIss'
- $ref: '#/components/parameters/kcCode'
/token_refresh:
get:
x-openapi-router-controller: fleetv2_http_api.impl.controllers
operationId: token_refresh
security: []
description:
"Endpoint to receive jwt token from refresh token."
tags:
- login
responses:
'200':
description: Returns a new standard keycloak token.
'500':
description: Token refresh failed due to internal server error.
parameters:
- $ref: '#/components/parameters/RefreshToken'
/cars:
get:
x-openapi-router-controller: fleetv2_http_api.impl.controllers
operationId: available_cars
description:
"Return list of available cars for all companies registered in the database."
tags:
- car
responses:
'200':
description: A list of available cars.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Car'
example:
- company_name: 'company_x'
car_name: 'basic_car'
- company_name: 'company_x'
car_name: 'better_car'
- company_name: 'competing_company'
car_name: 'even_better_car'
'500':
description: Cannot display available cars due to internal server error.
parameters:
- $ref: '#/components/parameters/Wait'
- $ref: '#/components/parameters/Since'
/available-devices/{company_name}/{car_name}:
get:
x-openapi-router-controller: fleetv2_http_api.impl.controllers
operationId: available-devices
description:
Return device Ids for all devices available for contained in the specified car.<br>
For a single car module, the device Ids are returned as an object containing module Id and the list of device Ids. <br>
If a module Id is specified, only a single such object is returned. <br>
Otherwise, a list of such objects is returned, one for each module contained in the car. <br>
tags:
- module
responses:
'200':
description: A list of available devices.
content:
application/json:
schema:
$ref: '#/components/schemas/AvailableDevices'
'404':
description: Cannot display available devices. Either company, car or module specified in the request does not exist.
'500':
description: Cannot display available devices due to internal server error.
parameters:
- $ref: '#/components/parameters/CompanyName'
- $ref: '#/components/parameters/CarName'
- $ref: "#/components/parameters/ModuleId"
/status/{company_name}/{car_name}:
parameters:
- $ref: '#/components/parameters/CompanyName'
- $ref: '#/components/parameters/CarName'
get:
x-openapi-router-controller: fleetv2_http_api.impl.controllers
operationId: list_statuses
description: It returns list of the Device Statuses.
tags:
- device
responses:
'200':
description: A list of device statuses.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Message'
example:
[
{
"timestamp": 1700139157,
device_id: {module_id: 47, type: 2, role: "test_device", name: "Test Device"},
payload: {message_type: "STATUS", encoding: "BASE64", data: "V2FpdGluZw=="}
},
{
"timestamp": 1700145485,
device_id: {module_id: 47, type: 2, role: "test_device", name: "Test Device"},
payload: {message_type: "STATUS", encoding: "BASE64", data: "U3RpbGwgd29ya2luZw=="}
},
{
"timestamp": 1700145490,
device_id: {module_id: 47, type: 2, role: "test_device", name: "Test Device"},
payload: {message_type: "STATUS", encoding: "JSON", data: {"description": "Still working"}}
},
]
'404':
description: The statuses cannot be displayed. Either company, car or device specified in the request does not exist.
'500':
description: The statuses cannot be displayed due to internal server error.
parameters:
- $ref: '#/components/parameters/Since'
- $ref: '#/components/parameters/Wait'
post:
x-openapi-router-controller: fleetv2_http_api.impl.controllers
operationId: send_statuses
description: Add statuses received from the Device.
tags:
- device
responses:
'200':
description: The statuses have been sent.
'404':
description: The statuses could not been sent. Either company, car or device specified in the request does not exist.
'500':
description: The statuses could not been sent due to internal server error.
requestBody:
description: Statuses to be send by the device.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Message'
example:
[
{
device_id: {module_id: 47, type: 0, role: "test_device", name: "Test Device"},
payload: {message_type: "STATUS", encoding: "BASE64", data: "QnJpbmdBdXRv"}
},
]
/command/{company_name}/{car_name}:
get:
x-openapi-router-controller: fleetv2_http_api.impl.controllers
operationId: list_commands
description: Returns list of the Device Commands.
tags:
- device
responses:
'200':
description: A list of commands.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Message'
example:
[
{
"timestamp": 1700139157,
device_id: {module_id: 47, type: 2, role: "test_device", name: "Test Device"},
payload: {message_type: "COMMAND", encoding: "BASE64", data: "U2F5IGhlbGxv"}
},
]
'404':
description: The commands cannot be displayed. Either company, car or device specified in the request does not exist.
'500':
description: The commands cannot be displayed due to internal server error.
parameters:
- $ref: '#/components/parameters/Since'
- $ref: '#/components/parameters/Wait'
parameters:
- $ref: '#/components/parameters/CompanyName'
- $ref: '#/components/parameters/CarName'
post:
x-openapi-router-controller: fleetv2_http_api.impl.controllers
operationId: send_commands
description: It adds new device Commands.
tags:
- device
requestBody:
description: Commands to be executed by the device.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Message'
example:
[
{
device_id: {module_id: 47, type: 2, role: "test_device", name: "Test Device"},
payload: {message_type: "COMMAND", encoding: "BASE64", data: "U2F5IGhlbGxv"}
},
]
responses:
'200':
description: The commands have been sent.
'404':
description: The commands have not been sent. Either company, car or device specified in the request does not exist.'
'500':
description: The commands have not been sent due to internal server error.
components:
securitySchemes:
AdminAuth:
description: Authentication token for a administrator.
type: apiKey
in: query
name: api_key
oAuth2AuthCode:
type: oauth2
description: oAuth2 authorization
flows:
authorizationCode:
authorizationUrl: https://keycloak.bringauto.com/realms/bringauto/protocol/openid-connect/auth
tokenUrl: https://keycloak.bringauto.com/realms/bringauto/protocol/openid-connect/token
refreshUrl: https://keycloak.bringauto.com/realms/bringauto/protocol/openid-connect/token
scopes: {}
parameters:
Since:
name: since
description: A Unix timestamp; if specified, the method returns all messages inclusivelly newer than the specified timestamp \
(i.e., messages with timestamp greater than or equal to the 'since' timestamp)
in: query
schema:
type: integer
nullable: true
default: 0
example: 1699262836
ModuleId:
name: module_id
description: An Id of module, an unsigned integer.
in: query
schema:
type: integer
minimum: 0
nullable: true
example: 47
Wait:
name: wait
description: An empty parameter. If specified, the method waits for predefined period of time, until some data to be sent in response are available.
in: query
schema:
type: boolean
nullable: true
default: false
example: false
CarName:
name: car_name
description: Name of the Car, following a pattern ^[0-9a-z_]+$.
in: path
required: true
schema:
type: string
pattern: ^[a-z0-9_]+$
example: "test_car"
CompanyName:
name: company_name
description: Name of the company, following a pattern ^[0-9a-z_]+$.
in: path
required: true
schema:
type: string
pattern: ^[0-9a-z_]+$
example: "test_company"
Device:
name: device
description: Device code used for assisted authentication.
in: query
required: false
schema:
type: string
example: e-VZfSM_-_TyPElL3i94...
kcState:
name: state
description: State returned by keycloak authentication.
in: query
required: false
schema:
type: string
example: your_state_info
kcSessionState:
name: session_state
description: Session state returned by keycloak authentication.
in: query
required: false
schema:
type: string
example: 167e141d-2f55-4d...
kcIss:
name: iss
description: Code issuer returned by keycloak authentication.
in: query
required: false
schema:
type: string
example: http%3A%2F%2Flocalhost%3A8081%2Frealms%2Fmaster
kcCode:
name: code
description: Code used for jwt token generation returned by keycloak authentication.
in: query
required: false
schema:
type: string
example: 5dea27d2-4b2d-48...
RefreshToken:
name: refresh_token
description: Refresh token used for jwt token generation.
in: query
required: true
schema:
type: string
example: eyJhbGciOiJIUzI1NiIsI...
schemas:
Message:
description: Physical device or program located on the car.
type: object
required:
- device_id
- payload
properties:
timestamp:
description: Unix timestamp of the message in milliseconds.
type: integer
example: 1699262836
device_id:
$ref: '#/components/schemas/DeviceId'
payload:
$ref: '#/components/schemas/Payload'
AvailableDevices:
description: List of Modules containint at least one device (specified by device Id) OR Module containing at least one device (specified by device Id).
oneOf:
- type: array
items:
$ref: '#/components/schemas/Module'
- $ref: '#/components/schemas/Module'
Module:
description: A module containing at least one device (specified by device Id).
type: object
required:
- module_id
- device_list
properties:
module_id:
description: Id (unsigned integer) of the module.
type: integer
minimum: 0
example: 47
device_list:
description: List of Ids of devices contained in the module.
type: array
items:
$ref: '#/components/schemas/DeviceId'
example:
[
{module_id: 47, type: 2, role: "test_device", name: "Test Device"},
{module_id: 47, type: 2, role: "test_device", name: "Test Device"},
]
Car:
description: A car assigned to a particular company.
type: object
required:
- company_name
- car_name
properties:
company_name:
description: Name of the company, following a pattern ^[0-9a-z_]+$
type: string
pattern: ^[0-9a-z_]+$
example: "test_company"
car_name:
description: Name of the Car, following a pattern ^[0-9a-z_]+$
type: string
pattern: ^[0-9a-z_]+$
example: "test_car"
DeviceId:
description: Id of the device described with an object.
type: object
required:
- module_id
- type
- role
- name
properties:
module_id:
description: Id (unsigned integer) of the module containing the device.
type: integer
minimum: 0
type:
description: Unsigned integer.
type: integer
minimum: 0
role:
description: "String description of the device role. It follows pattern ^[a-z0-9_]+$."
type: string
format: utf-8
pattern: ^[a-z0-9_]+$
name:
description: UTF-8 encoded string.
type: string
format: utf-8
example:
module_id: 47
type: 2
role: "test_device"
name: "Test Device"
Payload:
type: object
description: Payload of the message, containing message type (status or command), encoding and data.
required:
- message_type
- encoding
- data
properties:
message_type:
description: 'Type of the payload'
type: string
pattern: ^(STATUS)|(COMMAND)|(STATUS_ERROR)$
encoding:
description: 'Encoding of the payload'
type: string
pattern: ^(JSON)|(BASE64)$
data:
description: 'Payload data in "JSON" or "BASE64" format, depending on the encoding.'
oneOf:
- type: object
- type: array
items: {}
- type: string
format: base
example:
message_type: "STATUS"
encoding: "BASE64"
data: "QnJpbmdBdXRv"
# Cleaning up the statuses/commands:
#
# - every command and status has a TIMESTAMP and a KEY denoting a device,
# to/by which the command/status was sent
#
# - on a regular basis (e.g., every minute), a part of commands/statuses is deleted,
# if their timestamp is less or equal to current timestamp minus some specified period (e.g., 1 hour)
#
# - the method for posting new commands automatically detects, if a device key assigned
# to this new command also correspond to at least on status in the database.
# If not, the command is rejected
#
# - it is possible, that some commands remain in the database, whose device key does not now belong
# to any status
#
# - if after N minutes a new status is posted with the device key assigned, that was once assigned
# to other status (now deleted) in the database, all the commands having the same device key assigned
# have to be deleted from the database. If the timestamp of such a command is GREATER, a warning
# should be raised/logged (it is an invalid timestamp value, because, as mentioned previously,
# no command could have been added after deleting the last status with the given device key)