This repository has been archived by the owner on Nov 2, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 7
/
openapi.yaml
237 lines (227 loc) · 9.14 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
openapi: 3.0.3
info:
title: ct-diag-server
description: |-
[](https://circleci.com/gh/dstotijn/ct-diag-server)
[](https://coveralls.io/github/dstotijn/ct-diag-server?branch=master)
[](LICENSE)
[](https://godoc.org/github.com/dstotijn/ct-diag-server)
[](https://goreportcard.com/report/github.com/dstotijn/ct-diag-server)
**ct-diag-server** is an HTTP server written in Go for storing and retrieving
Diagnosis Keys, as defined in Apple/Google's [draft specification](https://www.apple.com/covid19/contacttracing/)
of its Contact Tracing Framework. It aims to respect the privacy of its users
and store only the bare minimum of data needed for anonymous contact tracing.
In anticipation of the general release of Apple and Google's native APIs (planned
for May 2020), this application provides a bare bones implementation for the
framework's server component: a central repository for submitting Diagnosis Keys
after a positive test, and retrieving a collection of all previously submitted
Diagnosis Keys.
contact:
name: David Stotijn
email: [email protected]
license:
name: MIT
url: https://github.com/dstotijn/ct-diag-server/blob/master/LICENSE
version: 0.8.0
externalDocs:
url: https://github.com/dstotijn/ct-diag-server
servers:
- url: https://ct-diag-server.v0x.nl/
paths:
/diagnosis-keys:
get:
description: |
To be used for fetching a list of Diagnosis Keys. A typical client is either a mobile device, or an intermediate platform/server of an app developer, for manual/custom distribution of the payload to clients. In either case, the keyset can be regarded as public; it doesn't contain PII.
The endpoint supports byte range requests as defined in [RFC 7233](https://tools.ietf.org/html/rfc7233).
The `HEAD` method may be used to obtain `Last-Modified` and `Content-Length` headers
for cache control purposes.
A `200 OK` response should be expected for normal requests (non-empty and empty),
and `206 Partial Content` for responses to byte range requests.
In case of an empty reply, a `Content-Length: 0` header is written.
A `500 Internal Server Error` response indicates server failure, and warrants a retry
The HTTP request body should be a bytestream of `1 <= n` Diagnosis Keys, where
`n` is the max upload batch size configured on the server (default: 14).
A diagnosis key consists of three parts: the `TemporaryExposureKey` itself (16 bytes), the `RollingStartNumber` (4 bytes, big endian) and the `TransmissionRiskLevel` (1 byte).
Because the amount of bytes per Diagnosis Key is fixed, there is no delimiter
parameters:
- name: after
in: query
description: |-
Used for listing diagnosis keys uploaded after the given key. Format: hexadecimal encoding of a Temporary Exposure Key.
example: a7752b99be501c9c9e893b213ad82842
required: false
style: form
explode: true
schema:
type: string
responses:
"200":
description: Successful response
headers:
Content-Length:
description:
Is `n * 21`, where `n` is the amount of found Diagnosis
Keys.
style: simple
explode: false
schema:
type: integer
example: 42000
Last-Modified:
description: The last modified date of the cache.
style: simple
explode: false
schema:
type: string
example: Sun, 03 May 2020 13:13:14 GMT
content:
application/octet-stream:
schema:
type: string
format: binary
"206":
description: Partial Content
headers:
Content-Length:
description:
Is `n * 21`, where `n` is the amount of found Diagnosis
Keys.
style: simple
explode: false
schema:
type: integer
example: 42000
Last-Modified:
description: The last modified date of the cache.
style: simple
explode: false
schema:
type: string
example: Sun, 03 May 2020 13:13:14 GMT
content:
application/octet-stream:
schema:
type: string
format: binary
"500":
description: Unexpected error
content:
text/plain; charset=utf-8:
schema:
type: string
example: Internal Server Error
post:
description: |-
To be used for uploading a set of Diagnosis Keys by a mobile client device.
**Note:** It's still undecided if this server should authenticate requests. Given the
wide range of per-country use cases and processes, this is now delegated to the server
operator to shield this endpoint against unauthorized access, and provide its own
upstream proxy, e.g. tailored to handle auth-z for health personnel.
The HTTP request body should be a bytestream of `1 <= n` Diagnosis Keys, where
`n` is the max upload batch size configured on the server (default: 14).
A diagnosis key consists of two parts: the `TemporaryExposureKey` itself (16 bytes),
and 2 bytes (big endian) to denote the `ENIntervalNumber` (see above). Because
the amount of bytes per diagnosis key is fixed, there is no delimiter.
A `200 OK` response with body `OK` should be expected on successful storage of the
keyset in the database.
A `400 Bad Request` response is used for client errors. A `500 Internal Server Error`
response is used for server errors, and warrants a retry. Error reasons are written
in a `text/plain; charset=utf-8` response body.
Duplicate keys are silently ignored.
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
"200":
description: Successful response
content:
application/octet-stream:
schema:
type: string
format: binary
"400":
description: Client error
content:
text/plain; charset=utf-8:
schema:
type: string
example: "Invalid Body: unexpected EOF"
"500":
description: Unexpected error
content:
text/plain; charset=utf-8:
schema:
type: string
example: Internal Server Error
/exposure-config:
get:
description:
To be used for fetching an [ENExposureConfiguration](https://developer.apple.com/documentation/exposurenotification/enexposureconfiguration)
object (see Apple‘s [sample code](https://developer.apple.com/documentation/exposurenotification/building_an_app_to_notify_users_of_covid-19_exposure#3587485)
article).
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/ExposureConfiguration"
/health:
get:
description: Health check. To be used for checking if the server is operational.
responses:
"200":
description: Successful response
content:
text/plain; charset=utf-8:
schema:
type: string
example: OK
components:
schemas:
ExposureConfiguration:
type: object
properties:
minimumRiskScore:
type: integer
format: uint8
example: 0
attenuationLevelValues:
type: array
items:
type: integer
format: uint8
attenuationWeight:
type: number
format: double
example: 50
daysSinceLastExposureLevelValues:
type: array
items:
type: integer
format: uint8
daysSinceLastExposureWeight:
type: number
format: double
example: 50
durationLevelValues:
type: array
items:
type: integer
format: uint8
durationWeight:
type: number
format: double
example: 50
transmissionRiskLevelValues:
type: array
items:
type: integer
format: uint8
transmissionRiskWeight:
type: number
format: double
example: 50