Skip to content

Commit a96432b

Browse files
johnnzhoujohnnzhou
committed
init: add openapi spec for coverage apis
1 parent d739fe8 commit a96432b

26 files changed

+1121
-0
lines changed

‎openapi/ccn-coverage-api.yaml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
openapi: 3.1.0
2+
info:
3+
title: CCN Coverage API
4+
description: CCN Coverage API documentation.
5+
version: 1.0.0
6+
7+
servers:
8+
- url: https://coverage.seattlecommunitynetwork.org/api
9+
10+
paths:
11+
/register:
12+
$ref: './register.yaml'
13+
/report_signal:
14+
$ref: './report_signal.yaml'
15+
/report_measurement:
16+
$ref: './report_measurement.yaml'
17+
/data:
18+
$ref: './data.yaml'
19+
/sucess:
20+
$ref: './success.yaml'
21+
/failure:
22+
$ref: './failure.yaml'
23+
/sitesSummary:
24+
$ref: './sites_summary.yaml'
25+
/lineSummary:
26+
$ref: './line_summary.yaml'
27+
/markers:
28+
$ref: './marker.yaml'
29+
/secure/get_groups:
30+
$ref: './get_groups.yaml'
31+
/secure/delete_group:
32+
$ref: './delete_group.yaml'
33+
/secure/delete_manual:
34+
$ref: './delete_manual.yaml'
35+
/secure/upload_data:
36+
$ref: './upload_data.yaml'
37+
/secure/get-users:
38+
$ref: './get_users.yaml'
39+
/secure/toggle-users:
40+
$ref: './toggle_users.yaml'
41+
/secure/login:
42+
$ref: './login.yaml'
43+
/secure/logout:
44+
$ref: './logout.yaml'
45+
/secure/edit_sites:
46+
$ref: './edit_sites.yaml'
47+
/secure/new_user:
48+
$ref: './new_user.yaml'

‎openapi/components.yaml‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
components:
2+
securitySchemes:
3+
sessionAuth:
4+
type: apiKey
5+
in: cookie
6+
name: connect.sid
7+
description: Session cookie for authenticated users
8+
9+
schemas:
10+
NewUserRequest:
11+
type: object
12+
properties:
13+
email:
14+
type: string
15+
format: email
16+
example: "[email protected]"
17+
description: User's email address
18+
firstName:
19+
type: string
20+
example: "John"
21+
description: User's first name
22+
lastName:
23+
type: string
24+
example: "Doe"
25+
description: User's last name
26+
LdapCredentials:
27+
type: object
28+
required:
29+
- username
30+
- password
31+
properties:
32+
username:
33+
type: string
34+
description: LDAP username (could be DN, uid, or email depending on LDAP configuration)
35+
example: "uid=jsmith,ou=users,dc=example,dc=com"
36+
password:
37+
type: string
38+
format: password
39+
description: LDAP password
40+
example: "password123"
41+
CryptoIdentityResponse:
42+
type: object
43+
properties:
44+
sigma_t:
45+
type: string
46+
description: Cryptographic signature in hexadecimal format
47+
example: "30450221009d41a9afd..."
48+
sk_t:
49+
type: string
50+
description: Private key in DER format converted to hexadecimal
51+
example: "308184020100301006..."
52+
pk_a:
53+
type: string
54+
description: Public key in DER format converted to hexadecimal
55+
example: "3056301006072a8648..."
56+
UploadDataRequest:
57+
type: object
58+
required:
59+
- csv
60+
properties:
61+
csv:
62+
type: string
63+
description: CSV data to be parsed and stored
64+
example: "date,time,coordinate,cell_id,dbm,ping,download_speed,upload_speed\n2021-01-25,18:43:54,47.681932,-122.318292,cell-1,-85.3,-87.1,137.4,5.2,7.3"
65+
group:
66+
type: string
67+
description: Optional group identifier to associate with uploaded data
68+
example: "fieldtrip-2021"
69+
DeleteGroupRequest:
70+
type: object
71+
required:
72+
- group
73+
properties:
74+
group:
75+
type: string
76+
description: Group identifier to delete
77+
example: "fieldtrip-2021"
78+
GroupList:
79+
type: array
80+
description: List of unique group identifiers across signal and measurement data
81+
items:
82+
type: string
83+
example: "fieldtrip-2021"
84+
User:
85+
type: object
86+
properties:
87+
identity:
88+
type: string
89+
description: Unique identifier for the user
90+
example: "9a8b7c6d5e4f3g2h1i"
91+
email:
92+
type: string
93+
format: email
94+
description: User's email address
95+
example: "[email protected]"
96+
firstName:
97+
type: string
98+
description: User's first name
99+
example: "John"
100+
lastName:
101+
type: string
102+
description: User's last name
103+
example: "Doe"
104+
registered:
105+
type: boolean
106+
description: Whether the user has completed registration
107+
example: true
108+
issueDate:
109+
type: string
110+
format: date-time
111+
description: Date when the user was issued or account was created
112+
example: "2023-03-15T14:30:45.123Z"
113+
isEnabled:
114+
type: boolean
115+
description: Whether the user account is currently enabled
116+
example: true
117+
publicKey:
118+
type: string
119+
description: User's public key
120+
example: "308201a2300d06092a864886f70d01010105000382018f003082018a02820181..."
121+
qrCode:
122+
type: string
123+
description: QR code data for user registration
124+
example: "{\"sigma_t\":\"...\",\"sk_t\":\"...\",\"pk_a\":\"...\"}"
125+
126+
UserListResponse:
127+
type: object
128+
properties:
129+
pending:
130+
type: array
131+
description: List of pending users (not yet registered) whose issue date is within the expiry limit
132+
items:
133+
$ref: '#/components/schemas/User'
134+
registered:
135+
type: array
136+
description: List of registered users
137+
items:
138+
$ref: '#/components/schemas/User'
139+
ToggleUserRequest:
140+
type: object
141+
required:
142+
- identity
143+
- enabled
144+
properties:
145+
identity:
146+
type: string
147+
description: Unique identifier of the user to update
148+
example: "9a8b7c6d5e4f3g2h1i"
149+
enabled:
150+
type: boolean
151+
description: New enabled status for the user
152+
example: true

‎openapi/data.yaml‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
get:
2+
summary: Retrieve network data
3+
description: Fetches network data with optional filtering by cell_id or timestamp range. When filtering by timestamp, both timestamp_from and timestamp_to must be provided together to define a date range. Results are always sorted by timestamp.
4+
parameters:
5+
- name: cell_id
6+
in: query
7+
description: Filter results by cell identifier
8+
required: false
9+
schema:
10+
type: string
11+
example: "Filipino Community Center"
12+
- name: timestamp_from
13+
in: query
14+
description: Start of timestamp range - must be used together with timestamp_to
15+
required: false
16+
schema:
17+
type: string
18+
format: date-time
19+
example: "2021-03-25T06:56:36.806Z"
20+
- name: timestamp_to
21+
in: query
22+
description: End of timestamp range - must be used together with timestamp_from
23+
required: false
24+
schema:
25+
type: string
26+
format: date-time
27+
example: "2021-03-30T03:05:12.867Z"
28+
responses:
29+
'200':
30+
description: A list of network data records, sorted by timestamp
31+
content:
32+
application/json:
33+
schema:
34+
type: array
35+
items:
36+
type: object
37+
required:
38+
- _id
39+
- latitude
40+
- longitude
41+
- timestamp
42+
- upload_speed
43+
- download_speed
44+
- data_since_last_report
45+
- ping
46+
- cell_id
47+
- device_id
48+
properties:
49+
_id:
50+
type: string
51+
description: Unique identifier for the record
52+
example: "614157263c28e1a473ede843"
53+
latitude:
54+
type: number
55+
format: double
56+
description: Geographic latitude coordinate
57+
example: 47.681932654395915
58+
longitude:
59+
type: number
60+
format: double
61+
description: Geographic longitude coordinate
62+
example: -122.31829217664796
63+
timestamp:
64+
type: string
65+
format: date-time
66+
description: Time when the measurement was recorded
67+
example: "2021-01-25T18:43:54.370Z"
68+
upload_speed:
69+
type: number
70+
format: double
71+
description: Upload speed measurement
72+
example: 7.289173724717997
73+
download_speed:
74+
type: number
75+
format: double
76+
description: Download speed measurement
77+
example: 5.234371563131994
78+
data_since_last_report:
79+
type: number
80+
format: double
81+
description: Amount of data transferred since the previous report
82+
example: 735.2343217314725
83+
ping:
84+
type: number
85+
format: double
86+
description: Network latency measurement
87+
example: 137.41470114174285
88+
cell_id:
89+
type: string
90+
description: Identifier for the cell/location where data was collected
91+
example: "Filipino Community Center"
92+
device_id:
93+
type: string
94+
description: Identifier for the device that collected the data
95+
example: "1e683a49d71ffd0"
96+
'400':
97+
description: Invalid input

‎openapi/delete_group.yaml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
post:
2+
summary: Delete a group of measurements
3+
description: Removes all measurements associated with the specified group
4+
security:
5+
- sessionAuth: []
6+
requestBody:
7+
required: true
8+
content:
9+
application/json:
10+
schema:
11+
$ref: './components.yaml#/components/schemas/DeleteGroupRequest'
12+
responses:
13+
'200':
14+
description: Successfully deleted group
15+
content:
16+
text/plain:
17+
schema:
18+
type: string
19+
example: "successfully deleted"
20+
description: Success message
21+
'401':
22+
description: Unauthorized - redirects to /api/failure
23+
'500':
24+
description: Server error
25+
content:
26+
text/plain:
27+
schema:
28+
type: string
29+
example: "database error"
30+
description: Error message

‎openapi/delete_manual.yaml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
post:
2+
summary: Delete manual measurements
3+
description: Removes all manually entered measurements from the database
4+
security:
5+
- sessionAuth: []
6+
responses:
7+
'200':
8+
description: Successfully deleted manual measurements
9+
content:
10+
text/plain:
11+
schema:
12+
type: string
13+
example: "successfully deleted"
14+
description: Success message
15+
'401':
16+
description: Unauthorized - redirects to /api/failure
17+
'500':
18+
description: Server error
19+
content:
20+
text/plain:
21+
schema:
22+
type: string
23+
example: "database error"
24+
description: Error message

0 commit comments

Comments
 (0)