Skip to content

Commit 90ef6b6

Browse files
BenjaminPelletierBenjaminPelletier
authored
Add general-purpose versioning API (#13)
* Add versioning API * Link to API from main README
1 parent ee4c9d9 commit 90ef6b6

File tree

7 files changed

+109
-28
lines changed

7 files changed

+109
-28
lines changed

‎README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,5 @@ This repository houses the interfaces a USS/USSP must implement in order to be t
1717
* [v1 YAML](scd/v1/scd.yaml)
1818
* [Flight planning](flight_planning/README.md)
1919
* [v1 YAML](flight_planning/v1/flight_planning.yaml)
20+
* [Versioning](versioning/README.md)
21+
* [YAML](versioning/versioning.yaml)

‎flight_planning/v1/flight_planning.yaml

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
openapi: 3.0.2
22
info:
33
title: Flight Planning Automated Testing Interface
4-
version: 0.1.0
4+
version: 0.2.0
55
description: >-
66
This interface is implemented by a USS wishing to participate in automated tests involving attempts to plan flights.
77
@@ -47,21 +47,16 @@ components:
4747
type: string
4848
enum: [Starting, Ready]
4949
example: Ready
50-
system_version:
51-
description: |-
52-
Arbitrary string representing the version of the USS system to be tested.
53-
type: string
54-
example: v0.0.1-445ad3
5550
api_name:
5651
description: |-
5752
Indication of the API implemented at this URL. Must be "Flight Planning Automated Testing Interface".
5853
type: string
5954
example: Flight Planning Automated Testing Interface
6055
api_version:
6156
description: |-
62-
Indication of the API version implemented at this URL. Must be "v0.1.0" when implementing this version of the API.
57+
Indication of the API version implemented at this URL. Must be "v0.2.0" when implementing this version of the API.
6358
type: string
64-
example: v0.1.0
59+
example: v0.2.0
6560

6661
FlightPlan:
6762
description: >-

‎geo-awareness/v1/geo-awareness.yaml

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
openapi: 3.0.2
22
info:
33
title: Geo-Awareness Automated Test Interfaces
4-
version: 0.1.0
4+
version: 0.2.0
55
license:
66
name: Apache License v2.0
77
url: https://github.com/interuss/dss/blob/master/LICENSE
@@ -53,11 +53,6 @@ components:
5353
type: string
5454
enum: [Starting, Ready]
5555
example: Ready
56-
version:
57-
description: |-
58-
Arbitrary string representing the version of the USS system to be tested.
59-
type: string
60-
example: v0.0.1-445ad3
6156

6257
CreateGeozoneSourceRequest:
6358
type: object

‎geospatial_map/v1/geospatial_map.yaml

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
openapi: 3.0.2
22
info:
33
title: Geospatial Map Provider Automated Testing Interface
4-
version: 0.1.0
4+
version: 0.2.0
55
license:
66
name: Apache License v2.0
77
url: https://github.com/interuss/automated_testing_interfaces/blob/main/LICENSE.md
@@ -63,21 +63,16 @@ components:
6363
type: string
6464
enum: [Starting, Ready]
6565
example: Ready
66-
system_version:
67-
description: |-
68-
Arbitrary string representing the version of the USS system to be tested.
69-
type: string
70-
example: v0.0.1-445ad3
7166
api_name:
7267
description: |-
7368
Indication of the API implemented at this URL. Must be "Geospatial Map Provider Automated Testing Interface".
7469
type: string
7570
example: Geospatial Map Provider Automated Testing Interface
7671
api_version:
7772
description: |-
78-
Indication of the API version implemented at this URL. Must be "v0.1.0" when implementing this version of the API.
73+
Indication of the API version implemented at this URL. Must be "v0.2.0" when implementing this version of the API.
7974
type: string
80-
example: v0.1.0
75+
example: v0.2.0
8176

8277
CreateGeospatialDataSourceRequest:
8378
type: object

‎scd/v1/scd.yaml

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
openapi: 3.0.2
22
info:
33
title: Strategic Coordination Test Data Injection
4-
version: 0.1.0
4+
version: 0.2.0
55
description: >-
66
This interface is implemented by every USS wishing to enable the automated testing framework to interact with the
77
USS as a user planning flights. This interaction capability is required by some automated tests.
@@ -35,11 +35,6 @@ components:
3535
type: string
3636
enum: [Starting, Ready]
3737
example: Ready
38-
version:
39-
description: |-
40-
Arbitrary string representing the version of the USS system to be tested.
41-
type: string
42-
example: v0.0.1-445ad3
4338
################################################################################
4439
#################### Start of ASTM-standard definitions #####################
4540
#################### interfaces/astm-utm/Protocol/utm.yaml #####################

‎versioning/README.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Versioning automated testing interface
2+
3+
## Purpose
4+
5+
The goal of automated testing is to verify that a system under test meets desired sets of requirements. The primary statement a test participant generally wants to make after successfully completing an automated test run is that their system under test has been verified to be compliant with one or more particular sets of requirements. But, this statement begs the question of which system was under test.
6+
7+
The API is intended to allow USSs to identify the exact system under test (by reporting its version) at the time the test is conducted. Under typical release practices, a release candidate would be required to pass automated tests in a qualification environment before being promoted to production. Under those practices, the expectation would be that the version of software in production always matches a version with a passing test report in the qualification environment. This interface provides the means by which that version can be determined both in the qualification environment during test and in production (for verification of these release practices).
8+
9+
## Overview
10+
11+
[This API](versioning.yaml) is designed to enable USSs to respond to the question, "What version of your system is running?" This question is complicated by the fact that a USS needs a clear definition of the scope of "system" in order to answer the question meaningfully. Rather than try to create that system scope/boundary definition itself, this API resolves this question by allowing the questioner to refer to a system boundary definition defined external to this interface but known to both the USS and the questioner.

‎versioning/versioning.yaml

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
openapi: 3.0.2
2+
info:
3+
title: Versioning Automated Testing Interface
4+
version: 0.1.0
5+
description: >-
6+
This interface is implemented by a USS wishing to provide information about the version(s) of its software to
7+
authorized recipients in an automated fashion.
8+
9+
Note: Unless otherwise specified, fields specified in a message but not declared in the API or otherwise known to
10+
the server or client (as applicable) must be ignored.
11+
12+
components:
13+
securitySchemes:
14+
Authority:
15+
type: oauth2
16+
flows:
17+
clientCredentials:
18+
tokenUrl: https://auth.example.com/oauth/token
19+
scopes:
20+
interuss.versioning.read_system_versions: |-
21+
Client may read the version(s) of the USS's software deployed in this environment.
22+
description: |-
23+
Authorization from, or on behalf of, an authorization authority, for the purpose of facilitating automated testing.
24+
25+
schemas:
26+
SystemBoundaryIdentifier:
27+
type: string
28+
description: >-
29+
Identifier of a system boundary, known to both the client and the USS separate from this API, for which a USS
30+
can provide a version. While the format is not prescribed by this API, any value must be URL-safe. It is
31+
recommended to use an approach similar to reverse-order Internet domain names and Java packages where the global
32+
scope is described with increasingly-precise identifiers joined by periods. For instance, the system boundary
33+
containing the mandatory Network Identification U-space service might be identified with
34+
`gov.eu.uspace.v1.netid` because the authority defining this system boundary is a governmental organization
35+
(specifically, the European Union) with requirements imposed on the system under test by the U-space regulation
36+
(first version) -- specifically, the Network Identification Service section.
37+
example: gov.au.casa.operating_rules.v2_6
38+
39+
VersionIdentifier:
40+
type: string
41+
description: >-
42+
Identifier of a particular version of a system (defined by a known system boundary). While the format is not
43+
prescribed by this API, a semantic version (https://semver.org/) prefixed with a `v` is recommended.
44+
example: v2.19.53117-rc8+d3a7521f
45+
46+
GetVersionResponse:
47+
type: object
48+
properties:
49+
system_identity:
50+
description: The requested system identity/boundary.
51+
anyOf:
52+
- $ref: '#/components/schemas/SystemBoundaryIdentifier'
53+
system_version:
54+
description: The USS's version for the system with the specified system identity/boundary.
55+
anyOf:
56+
- $ref: '#/components/schemas/VersionIdentifier'
57+
58+
paths:
59+
/versions/{system_identity}:
60+
parameters:
61+
- name: system_identity
62+
in: path
63+
required: true
64+
description: The system identity/boundary for which a version should be provided, if known.
65+
schema:
66+
$ref: '#/components/schemas/SystemBoundaryIdentifier'
67+
68+
get:
69+
security:
70+
- Authority:
71+
- interuss.versioning.read_system_versions
72+
responses:
73+
'200':
74+
content:
75+
application/json:
76+
schema:
77+
$ref: '#/components/schemas/GetVersionResponse'
78+
description: >-
79+
The USS successfully provided the version of the system identity/boundary that was requested.
80+
'401':
81+
description: Bearer access token was not provided in Authorization header, token could not be decoded, or token was invalid.
82+
'403':
83+
description: The access token was decoded successfully but did not include a scope appropriate to this endpoint.
84+
'404':
85+
description: The requested system identity/boundary is not known, or the versioning automated testing interface is not available.
86+
summary: System version
87+
description: Get the requested system version.
88+
operationId: GetVersion

0 commit comments

Comments
 (0)