Skip to content

Commit a10438b

Browse files
clundie-CLclundie-CL
committed
85 alpha release checklist (camaraproject#100)
* fix: reset versions back to 'wip' * fix: remove info.contact field per section 5.3.5 of API Design Guide * fix: add missing externalDocs stanza per section 5.4 of API Design Guide * fix: update CAMARA_common.yaml to v0.7.1 from r3.4 tag and remove placeholders * chore: update API Readiness Checklist * fix: removed duplicate Generic404 response schema * fix: addressed broken schema for experimental API
1 parent e544135 commit a10438b

6 files changed

Lines changed: 38 additions & 97 deletions

File tree

‎code/API_definitions/Domain/CAMARA_common.yaml‎

Lines changed: 5 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,20 @@
1-
# This file was pulled from https://github.com/camaraproject/Commonalities/commit/3735a9d38b09501b41f0dbe895177c8172986709
2-
# in order to reference Commonalities models directly from spec files using $ref statements. The
3-
# term FIXME is to use this same $ref approach but against a commonalities submodule that defines
4-
# this file.
1+
# This file was pulled from https://github.com/camaraproject/Commonalities/blob/r3.4/artifacts/CAMARA_common.yaml
2+
# in order to reference Commonalities models directly from spec files using $ref statements.
53
#
64
# IMPORTANT: This file has been modified in this repo in order to address linter warnings/errors that
75
# occurred in examples that referenced generic placeholder values like {{SPECIFIC_CODE}} or {{SPECIFIC_CODE_MESSAGE}}.
86
# The original file was using { { SPECIFIC_CODE } } in examples which had two issues. First, it's not quoted so it
97
# conform to the enum type (string). Second, even when quoted, the extraneous spaces inside the curly braces made it
10-
# not conform to the pattern defined for that field. The modifications made were to remove the spaces inside the curly braces
11-
# so that the examples now use '{{SPECIFIC_CODE}}'' instead of { { SPECIFIC_CODE } }. Other placeholders were updated similarly.
8+
# not conform to the pattern defined for that field. The modifications made were to remove any such placeholder entries
9+
# from the examples, while leaving the rest of the example intact.
1210
openapi: 3.0.3
1311
info:
1412
title: CAMARA common data types
1513
description: Common data types for CAMARA APIs
1614
license:
1715
name: Apache 2.0
1816
url: https://www.apache.org/licenses/LICENSE-2.0.html
19-
version: wip
17+
version: 0.7.1
2018
x-camara-commonalities: 0.6
2119

2220
paths: {}
@@ -302,7 +300,6 @@ components:
302300
enum:
303301
- INVALID_ARGUMENT
304302
- OUT_OF_RANGE
305-
- "{{SPECIFIC_CODE}}"
306303
examples:
307304
GENERIC_400_INVALID_ARGUMENT:
308305
description: Invalid Argument. Generic Syntax Exception
@@ -316,12 +313,6 @@ components:
316313
status: 400
317314
code: OUT_OF_RANGE
318315
message: Client specified an invalid range.
319-
GENERIC_400_{{SPECIFIC_CODE}}:
320-
description: Specific Syntax Exception regarding a field that is relevant in the context of the API
321-
value:
322-
status: 400
323-
code: '{{SPECIFIC_CODE}}'
324-
message: '{ { SPECIFIC_CODE_MESSAGE } }'
325316
Generic401:
326317
description: Unauthorized
327318
headers:
@@ -366,7 +357,6 @@ components:
366357
enum:
367358
- PERMISSION_DENIED
368359
- INVALID_TOKEN_CONTEXT
369-
- "{{SPECIFIC_CODE}}"
370360
examples:
371361
GENERIC_403_PERMISSION_DENIED:
372362
description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
@@ -380,12 +370,6 @@ components:
380370
status: 403
381371
code: INVALID_TOKEN_CONTEXT
382372
message: "{{field}} is not consistent with access token."
383-
GENERIC_403_{{SPECIFIC_CODE}}:
384-
description: Indicate a Business Logic condition that forbids a process not attached to a specific field in the context of the API
385-
value:
386-
status: 403
387-
code: '{{SPECIFIC_CODE}}'
388-
message: '{ { SPECIFIC_CODE_MESSAGE } }'
389373
Generic404:
390374
description: Not found
391375
headers:
@@ -405,7 +389,6 @@ components:
405389
enum:
406390
- NOT_FOUND
407391
- IDENTIFIER_NOT_FOUND
408-
- "{{SPECIFIC_CODE}}"
409392
examples:
410393
GENERIC_404_NOT_FOUND:
411394
description: Resource is not found
@@ -419,12 +402,6 @@ components:
419402
status: 404
420403
code: IDENTIFIER_NOT_FOUND
421404
message: Device identifier not found.
422-
GENERIC_404_{{SPECIFIC_CODE}}:
423-
description: Specific situation to highlight the resource/concept not found
424-
value:
425-
status: 404
426-
code: '{{SPECIFIC_CODE}}'
427-
message: '{ { SPECIFIC_CODE_MESSAGE } }'
428405
Generic405:
429406
description: Method Not Allowed
430407
headers:
@@ -495,7 +472,6 @@ components:
495472
- ABORTED
496473
- ALREADY_EXISTS
497474
- CONFLICT
498-
- "{{SPECIFIC_CODE}}"
499475
examples:
500476
GENERIC_409_ABORTED:
501477
description: Concurreny of processes of the same nature/scope
@@ -515,12 +491,6 @@ components:
515491
status: 409
516492
code: CONFLICT
517493
message: A specified resource duplicate entry found.
518-
GENERIC_409_{{SPECIFIC_CODE}}:
519-
description: Specific conflict situation that is relevant in the context of the API
520-
value:
521-
status: 409
522-
code: '{{SPECIFIC_CODE}}'
523-
message: '{ { SPECIFIC_CODE_MESSAGE } }'
524494
Generic410:
525495
description: Gone
526496
headers:
@@ -617,7 +587,6 @@ components:
617587
- MISSING_IDENTIFIER
618588
- UNSUPPORTED_IDENTIFIER
619589
- UNNECESSARY_IDENTIFIER
620-
- "{{SPECIFIC_CODE}}"
621590
examples:
622591
GENERIC_422_SERVICE_NOT_APPLICABLE:
623592
description: Service not applicable for the provided identifier
@@ -643,12 +612,6 @@ components:
643612
status: 422
644613
code: UNNECESSARY_IDENTIFIER
645614
message: The device is already identified by the access token.
646-
GENERIC_422_{{SPECIFIC_CODE}}:
647-
description: Any semantic condition associated to business logic, specifically related to a field or data structure
648-
value:
649-
status: 422
650-
code: '{{SPECIFIC_CODE}}'
651-
message: '{ { SPECIFIC_CODE_MESSAGE } }'
652615
Generic429:
653616
description: Too Many Requests
654617
headers:
@@ -806,5 +769,3 @@ components:
806769
status: 504
807770
code: TIMEOUT
808771
message: Request timeout exceeded.
809-
810-

‎code/API_definitions/Domain/Capabilities.yaml‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,20 @@
11
components:
2+
parameters:
3+
deviceId:
4+
name: deviceId
5+
in: path
6+
description: |
7+
The unique identifier of a Device. If the device exists but the caller lacks permission to access it, the API returns 403.
8+
9+
Must be a valid UUID as defined by RFC 4122 (versions 1-5) using only lowercase hexadecimal characters.
10+
required: true
11+
schema:
12+
$ref: "./NAM_Common.yaml#/components/schemas/UUID"
13+
214
schemas:
315
title: Operator Device Capabilities
416
DeviceId:
5-
$ref: "./Common.yaml#/components/schemas/DeviceId"
17+
$ref: "./NAM_Common.yaml#/components/schemas/DeviceId"
618

719
DeviceCapabilities:
820
oneOf:

‎code/API_definitions/Templates/capabilities-template.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ paths:
3333
- network-access-management:device:read
3434
operationId: getDeviceCapabilities
3535
parameters:
36-
- $ref: "../Domain/Common.yaml#/components/parameters/deviceIdParam"
36+
- $ref: "../Domain/Capabilities.yaml#/components/parameters/deviceId"
3737
responses:
3838
"200":
3939
description: Capabilities supported by the device

‎code/API_definitions/Templates/network-access-management-template.yaml‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,8 @@ info:
55
license:
66
name: Apache 2.0
77
url: https://www.apache.org/licenses/LICENSE-2.0.html
8-
version: 0.1.0-alpha.1
9-
x-camara-commonalities: 0.6.0
10-
contact:
11-
email: sp-nam@lists.camaraproject.org
8+
version: wip
9+
x-camara-commonalities: 0.6
1210
description: |
1311
Service enabling API for managing network operator supplied network access devices. This API's initial focus is on
1412
managing **Trust Domains** and device reboot requests.
@@ -169,8 +167,12 @@ info:
169167
170168
As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.
171169
170+
externalDocs:
171+
description: Product documentation at CAMARA
172+
url: https://github.com/camaraproject/NetworkAccessManagement
173+
172174
servers:
173-
- url: "{apiRoot}/network-access-management/v0"
175+
- url: "{apiRoot}/network-access-management/vwip"
174176
variables:
175177
apiRoot:
176178
default: http://localhost:9091

‎code/API_definitions/network-access-management.yaml‎

Lines changed: 6 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,8 @@ info:
44
license:
55
name: Apache 2.0
66
url: https://www.apache.org/licenses/LICENSE-2.0.html
7-
version: 0.1.0-alpha.1
8-
x-camara-commonalities: 0.6.0
9-
contact:
10-
email: sp-nam@lists.camaraproject.org
7+
version: wip
8+
x-camara-commonalities: 0.6
119
description: |
1210
Service enabling API for managing network operator supplied network access devices. This API's initial focus is on
1311
managing **Trust Domains** and device reboot requests.
@@ -168,7 +166,7 @@ info:
168166
169167
As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.
170168
servers:
171-
- url: "{apiRoot}/network-access-management/vwip"
169+
- url: '{apiRoot}/network-access-management/vwip'
172170
variables:
173171
apiRoot:
174172
default: http://localhost:9091
@@ -181,6 +179,9 @@ tags:
181179
- name: Reboot Requests
182180
description: |
183181
Operations to Create and Manage Reboot Requests for Network Access Devices
182+
externalDocs:
183+
description: Product documentation at CAMARA
184+
url: https://github.com/camaraproject/NetworkAccessManagement
184185
paths:
185186
/services:
186187
get:
@@ -2061,7 +2062,6 @@ components:
20612062
enum:
20622063
- PERMISSION_DENIED
20632064
- INVALID_TOKEN_CONTEXT
2064-
- '{{SPECIFIC_CODE}}'
20652065
examples:
20662066
GENERIC_403_PERMISSION_DENIED:
20672067
description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
@@ -2075,12 +2075,6 @@ components:
20752075
status: 403
20762076
code: INVALID_TOKEN_CONTEXT
20772077
message: '{{field}} is not consistent with access token.'
2078-
GENERIC_403_{{SPECIFIC_CODE}}:
2079-
description: Indicate a Business Logic condition that forbids a process not attached to a specific field in the context of the API
2080-
value:
2081-
status: 403
2082-
code: '{{SPECIFIC_CODE}}'
2083-
message: '{ { SPECIFIC_CODE_MESSAGE } }'
20842078
Generic500:
20852079
description: Internal Server Error
20862080
headers:
@@ -2125,7 +2119,6 @@ components:
21252119
enum:
21262120
- NOT_FOUND
21272121
- IDENTIFIER_NOT_FOUND
2128-
- '{{SPECIFIC_CODE}}'
21292122
examples:
21302123
GENERIC_404_NOT_FOUND:
21312124
description: Resource is not found
@@ -2139,12 +2132,6 @@ components:
21392132
status: 404
21402133
code: IDENTIFIER_NOT_FOUND
21412134
message: Device identifier not found.
2142-
GENERIC_404_{{SPECIFIC_CODE}}:
2143-
description: Specific situation to highlight the resource/concept not found
2144-
value:
2145-
status: 404
2146-
code: '{{SPECIFIC_CODE}}'
2147-
message: '{ { SPECIFIC_CODE_MESSAGE } }'
21482135
Generic503:
21492136
description: Service Unavailable
21502137
headers:
@@ -2189,7 +2176,6 @@ components:
21892176
enum:
21902177
- INVALID_ARGUMENT
21912178
- OUT_OF_RANGE
2192-
- '{{SPECIFIC_CODE}}'
21932179
examples:
21942180
GENERIC_400_INVALID_ARGUMENT:
21952181
description: Invalid Argument. Generic Syntax Exception
@@ -2203,12 +2189,6 @@ components:
22032189
status: 400
22042190
code: OUT_OF_RANGE
22052191
message: Client specified an invalid range.
2206-
GENERIC_400_{{SPECIFIC_CODE}}:
2207-
description: Specific Syntax Exception regarding a field that is relevant in the context of the API
2208-
value:
2209-
status: 400
2210-
code: '{{SPECIFIC_CODE}}'
2211-
message: '{ { SPECIFIC_CODE_MESSAGE } }'
22122192
Generic409:
22132193
description: Conflict
22142194
headers:
@@ -2229,7 +2209,6 @@ components:
22292209
- ABORTED
22302210
- ALREADY_EXISTS
22312211
- CONFLICT
2232-
- '{{SPECIFIC_CODE}}'
22332212
examples:
22342213
GENERIC_409_ABORTED:
22352214
description: Concurreny of processes of the same nature/scope
@@ -2249,12 +2228,6 @@ components:
22492228
status: 409
22502229
code: CONFLICT
22512230
message: A specified resource duplicate entry found.
2252-
GENERIC_409_{{SPECIFIC_CODE}}:
2253-
description: Specific conflict situation that is relevant in the context of the API
2254-
value:
2255-
status: 409
2256-
code: '{{SPECIFIC_CODE}}'
2257-
message: '{ { SPECIFIC_CODE_MESSAGE } }'
22582231
Generic422:
22592232
description: Unprocessable Content
22602233
headers:
@@ -2276,7 +2249,6 @@ components:
22762249
- MISSING_IDENTIFIER
22772250
- UNSUPPORTED_IDENTIFIER
22782251
- UNNECESSARY_IDENTIFIER
2279-
- '{{SPECIFIC_CODE}}'
22802252
examples:
22812253
GENERIC_422_SERVICE_NOT_APPLICABLE:
22822254
description: Service not applicable for the provided identifier
@@ -2302,12 +2274,6 @@ components:
23022274
status: 422
23032275
code: UNNECESSARY_IDENTIFIER
23042276
message: The device is already identified by the access token.
2305-
GENERIC_422_{{SPECIFIC_CODE}}:
2306-
description: Any semantic condition associated to business logic, specifically related to a field or data structure
2307-
value:
2308-
status: 422
2309-
code: '{{SPECIFIC_CODE}}'
2310-
message: '{ { SPECIFIC_CODE_MESSAGE } }'
23112277
examples:
23122278
TrustDomainCreateWpa2Personal:
23132279
summary: Create a Trust Domain with WPA2-Personal Wi-Fi access.

‎documentation/API_documentation/network-access-management-API-Readiness-Checklist.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,22 @@
11
# API Readiness Checklist
22

3-
Checklist for network-access-management 0.1.0-alpha.1 in r1.0-rc.1.
3+
Checklist for network-access-management 0.1.0-alpha.1 in r1.1.
44

55
| Nr | API release assets | alpha | release-candidate | initial<br>public | stable<br> public | Status | Reference information |
66
|----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:---------------:|
77
| 1 | API definition | M | M | M | M | Y | [relative link](../../code/API_definitions/network-access-management.yaml) |
8-
| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | r2.3 |
9-
| 3 | Guidelines from ICM applied | O | M | M | M | Y | r2.3 |
8+
| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | r3.4 |
9+
| 3 | Guidelines from ICM applied | O | M | M | M | Y | r3.3 |
1010
| 4 | API versioning convention applied | M | M | M | M | Y | |
1111
| 5 | API documentation | M | M | M | M | Y | inline in yaml |
1212
| 6 | User stories | O | O | O | M | N | |
1313
| 7 | Basic API test cases & documentation | O | M | M | M | N | |
1414
| 8 | Enhanced API test cases & documentation | O | O | O | M | N | |
1515
| 9 | Test result statement | O | O | O | M | N | |
16-
| 10 | API release numbering convention applied | M | M | M | M | Y | |
17-
| 11 | Change log updated | M | M | M | M | Y | [relative link](../../CHANGELOG.md) |
16+
| 10 | API release numbering convention applied | M | M | M | M | N | |
17+
| 11 | Change log updated | M | M | M | M | N | [relative link](../../CHANGELOG.md) |
1818
| 12 | Previous public release was certified | O | O | O | M | N | |
19-
| 13 | API description (for marketing) | O | O | M | M | | [wiki link](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/81166949/NetworkAccessManagement+API+description) |
19+
| 13 | API description (for marketing) | O | O | M | M | N | [wiki link](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/81166949/NetworkAccessManagement+API+description) |
2020

2121
To fill the checklist:
2222

0 commit comments

Comments
 (0)