forked from camaraproject/Commonalities
-
Notifications
You must be signed in to change notification settings - Fork 0
/
CAMARA_common.yaml
479 lines (469 loc) · 16.5 KB
/
CAMARA_common.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
openapi: 3.0.3
info:
title: Camara common data types
description: Common data types for Camara APIs
contact:
email: sp-com@lists.camaraproject.org
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 0.4.0-wip
paths: {}
components:
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
parameters:
x-correlator:
name: x-correlator
in: header
description: Correlation id for the different services
schema:
type: string
schemas:
TimePeriod:
properties:
startDate:
type: string
format: date-time
description: An instant of time, starting of the TimePeriod.
endDate:
type: string
format: date-time
description: An instant of time, ending of the TimePeriod. If not included, then the period has no ending date.
required:
- startDate
ErrorInfo:
type: object
required:
- message
- status
- code
properties:
message:
type: string
description: A human readable description of what the event represent
status:
type: integer
description: HTTP response status code
code:
type: string
description: Friendly Code to describe the error
Device:
description: |
End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.
The developer can choose to provide the below specified device identifiers:
* `ipv4Address`
* `ipv6Address`
* `phoneNumber`
* `networkAccessIdentifier`
NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device.
type: object
properties:
phoneNumber:
$ref: "#/components/schemas/PhoneNumber"
networkAccessIdentifier:
$ref: "#/components/schemas/NetworkAccessIdentifier"
ipv4Address:
$ref: "#/components/schemas/DeviceIpv4Addr"
ipv6Address:
$ref: "#/components/schemas/DeviceIpv6Address"
minProperties: 1
PhoneNumber:
description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
type: string
pattern: '^\+[1-9][0-9]{4,14}$'
example: "+123456789"
NetworkAccessIdentifier:
description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.
type: string
example: "123456789@domain.com"
DeviceIpv4Addr:
type: object
description: |
The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers).
If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress.
If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object)
In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone.
properties:
publicAddress:
$ref: "#/components/schemas/SingleIpv4Addr"
privateAddress:
$ref: "#/components/schemas/SingleIpv4Addr"
publicPort:
$ref: "#/components/schemas/Port"
anyOf:
- required: [publicAddress, privateAddress]
- required: [publicAddress, publicPort]
example:
publicAddress: "84.125.93.10"
publicPort: 59765
SingleIpv4Addr:
description: A single IPv4 address with no subnet mask
type: string
format: ipv4
example: "84.125.93.10"
Port:
description: TCP or UDP port number
type: integer
minimum: 0
maximum: 65535
DeviceIpv6Address:
description: |
The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).
type: string
format: ipv6
example: 2001:db8:85a3:8d3:1319:8a2e:370:7344
responses:
Generic400:
description: Bad Request
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_400_INVALID_ARGUMENT:
description: Invalid Argument. Generic Syntax Exception
value:
status: 400
code: INVALID_ARGUMENT
message: Client specified an invalid argument, request body or query param.
GENERIC_400_OUT_OF_RANGE:
description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
value:
status: 400
code: OUT_OF_RANGE
message: Client specified an invalid range.
GENERIC_400_{{SPECIFIC_CODE}}:
description: Specific Syntax Exception regarding a field that is relevant in the context of the API
value:
status: 400
code: {{SPECIFIC_CODE}}
message: {{SPECIFIC_CODE_MESSAGE}}
Generic401:
description: Unauthorized
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_401_UNAUTHENTICATED:
description: Request cannot be authenticated
value:
status: 401
code: UNAUTHENTICATED
message: Request not authenticated due to missing, invalid, or expired credentials.
GENERIC_401_AUTHENTICATION_REQUIRED:
description: New authentication is needed, authentication is no longer valid
value:
status: 401
code: AUTHENTICATION_REQUIRED
message: New authentication is required.
Generic403:
description: Forbidden
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_403_PERMISSION_DENIED:
description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
value:
status: 403
code: PERMISSION_DENIED
message: Client does not have sufficient permissions to perform this action.
GENERIC_403_INVALID_TOKEN_CONTEXT:
description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
value:
status: 403
code: INVALID_TOKEN_CONTEXT
message: "{{field}} is not consistent with access token."
GENERIC_403_{{SPECIFIC_CODE}}:
description: Indicate a Business Logic condition that forbids a process not attached to a specific field in the context of the API
value:
status: 403
code: {{SPECIFIC_CODE}}
message: {{SPECIFIC_CODE_MESSAGE}}
Generic404:
description: Not found
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_404_NOT_FOUND:
description: Resource is not found
value:
status: 404
code: NOT_FOUND
message: The specified resource is not found.
GENERIC_404_DEVICE_NOT_FOUND:
description: Device identifier not found
value:
status: 404
code: DEVICE_NOT_FOUND
message: Device identifier not found.
GENERIC_404_{{SPECIFIC_CODE}}:
description: Specific situation to highlight the resource/concept not found
value:
status: 404
code: {{SPECIFIC_CODE}}
message: {{SPECIFIC_CODE_MESSAGE}}
Generic405:
description: Method Not Allowed
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_405_METHOD_NOT_ALLOWED:
description: Invalid HTTP verb used with a given endpoint
value:
status: 405
code: METHOD_NOT_ALLOWED
message: The requested method is not allowed/supported on the target resource.
Generic406:
description: Not Acceptable
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_406_NOT_ACCEPTABLE:
description: API Server does not accept the media type (`Accept-*` header) indicated by API client
value:
status: 406
code: NOT_ACCEPTABLE
message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers.
Generic409:
description: Conflict
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_409_ABORTED:
description: Concurreny of processes of the same nature/scope
value:
status: 409
code: ABORTED
message: Concurrency conflict.
GENERIC_409_ALREADY_EXISTS:
description: Trying to create an existing resource
value:
status: 409
code: ALREADY_EXISTS
message: The resource that a client tried to create already exists.
GENERIC_409_CONFLICT:
description: Duplication of an existing resource
value:
status: 409
code: CONFLICT
message: A specified resource duplicate entry found.
GENERIC_409_{{SPECIFIC_CODE}}:
description: Specific conflict situation that is relevant in the context of the API
value:
status: 409
code: {{SPECIFIC_CODE}}
message: {{SPECIFIC_CODE_MESSAGE}}
Generic410:
description: Gone
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_410_GONE:
description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available
value:
status: 410
code: GONE
message: Access to the target resource is no longer available.
Generic412:
description: Failed precondition
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_412_FAILED_PRECONDITION:
description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available
value:
status: 412
code: FAILED_PRECONDITION
message: Request cannot be executed in the current system state.
Generic415:
description: Unsupported Media Type
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_415_UNSUPPORTED_MEDIA_TYPE:
description: Payload format of the request is in an unsupported format by the Server. Should not happen
value:
status: 415
code: UNSUPPORTED_MEDIA_TYPE
message: The server refuses to accept the request because the payload format is in an unsupported format.
Generic422:
description: Unprocessable Content
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH:
description: Inconsistency between device identifiers not pointing to the same device
value:
status: 422
code: DEVICE_IDENTIFIERS_MISMATCH
message: Provided device identifiers are not consistent.
GENERIC_422_DEVICE_NOT_APPLICABLE:
description: Service is not available for the provided device
value:
status: 422
code: DEVICE_NOT_APPLICABLE
message: The service is not available for the provided device.
GENERIC_422_{{SPECIFIC_CODE}}:
description: Any semantic condition associated to business logic, specifically related to a field or data structure
value:
status: 422
code: {{SPECIFIC_CODE}}
message: {{SPECIFIC_CODE_MESSAGE}}
Generic429:
description: Too Many Requests
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_429_QUOTA_EXCEEDED:
description: Request is rejected due to exceeding a business quota limit
value:
status: 429
code: QUOTA_EXCEEDED
message: Either out of resource quota or reaching rate limiting.
GENERIC_429_TOO_MANY_REQUESTS:
description: API Server request limit is overpassed
value:
status: 429
code: TOO_MANY_REQUESTS
message: Either out of resource quota or reaching rate limiting.
Generic500:
description: Internal Server Error
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_500_INTERNAL:
description: Problem in Server side. Regular Server Exception
value:
status: 500
code: INTERNAL
message: Unknown server error. Typically a server bug.
Generic501:
description: Not Implemented
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_501_NOT_IMPLEMENTED:
description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations
value:
status: 501
code: NOT_IMPLEMENTED
message: This functionality is not implemented yet.
Generic502:
description: Bad Gateway
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_502_BAD_GATEWAY:
description: Internal routing problem in the Server side that blocks to manage the service properly
value:
status: 502
code: BAD_GATEWAY
message: An upstream internal service cannot be reached.
Generic503:
description: Service Unavailable
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_503_UNAVAILABLE:
description: Service is not available. Temporary situation usually related to maintenance process in the server side
value:
status: 503
code: UNAVAILABLE
message: Service Unavailable.
Generic504:
description: Gateway Timeout
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorInfo"
examples:
GENERIC_504_TIMEOUT:
description: API Server Timeout
value:
status: 504
code: TIMEOUT
message: Request timeout exceeded.