-
Notifications
You must be signed in to change notification settings - Fork 2
/
apiary.apib
277 lines (185 loc) · 10.2 KB
/
apiary.apib
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
FORMAT: 1A
HOST: http://api.tidepool.org
# Tidepool Seagull
**"An archive is a dump without the seagulls."** -- *Perfesser Shoe, 1990 (McNally)*
## Overview
Seagull stores metadata about users.
Initially, it just stores blobs of JSON bound to a user ID and a collection name, but the intent is that said blobs will have specific,
versionable format types that will be registered with the API and enforced by it.
A collection is the name for a block of related data. Currently, we only support previously known collections. But someday we'll support the concept of a collection registry with a registered and enforced schema for each.
Please see the [data documentation](http://tidepool-org.github.io/ServerDataOrganization.html)
for further details on the data format.
General philosophy / notes:
* You can do the usual CRUD operations on collections.
* The "private" collection has special semantics -- only GET and DELETE are supported so far, and actually, DELETE returns 501 (unimplemented). A GET calling for a private value that does not already exist generates one and stores it, then returns it. (We plan to eventually support DELETE so that we can support moving private data to a different location in case of a security breach.)
* You can GET a collection and get a block of data corresponding to that collection.
* You can delete a field by setting its value to null.
* There's a /meta/private that is identical to the one in the user API.
We follow many of the usual RESTful guidelines.
* Our CRUD semantics:
* POST and PUT are identical; if a record doesn't exist, it is inserted by both verbs.
* POST and PUT do partial updates; if you POST ```{ c: 4, d: 4 }``` to a body already containing ```{ a: 1, b: 2, c: 3 }``` you will get ```{ a: 1, b: 2, c: 4, d: 4 }```
* If a PUT or POST was successful, you get a 200 and the created record is returned in the body.
* Read is done with GET. If not found, 404. If found, result is 200 with the record in the body.
* DELETE currently checks credentials, THEN returns 501 (unimplemented). We don't want to be deleting customer data without having a solid understanding
of why we're doing it and how to do it safely. In the short term, we just disallow it. But in the long term, we should let people
make their data go away if they really want it to. Successful DELETE returns a 204 (no data to delete)
## Notes for the blip pilot study release
The intent is that metadata will NOT include demographic information -- that will be found in a separate endpoint managed through the
/metadata/private/patient id/hash pair. But for the pilot, we're going to store metadata in this database.
The schema we will use for the pilot is as follows:
```
{
"fullname": "Jonathan Livingston",
"shortname": "Jonny",
"publicbio": "I fly far and fast. T1D is something I have, not who I am.",
"image_url": "https://files.tidepool.io/87263b8476fad2836486af125/me.jpg",
"patient": {
"sharable": false,
"health": {
diagnosisDate: "2010-08-10"
},
"demographic": {
birthDate: "1986-04-01",
country: "US",
region: "California",
postalcode: "94110",
gender: "male",
}
}
}
```
All demographic fields are optional and should support a null value or a missing field.
The sharable flag should default to false. It would be nice to have it in the UI with a question something like:
**May we share your demographic information anonymously with health researchers?** But if that raises too many questions for the pilot, we can just leave it as false for the pilot study.
*Note to developers -- if a different set of fields become necessary, please edit this document.*
# Group Metadata
Stores and retrieves blobs of JSON.
## Metadata Collection [/metadata/collections]
### Get permissible collections [GET]
Retrieves the set of allowed collection names. These are basically subdocuments from the top level document.
Someday this will also return the definitions of schema for the collections. But not yet.
+ Request
A current session token must come from the user-api. This can be a user token, in which case only specific information for that user is accessible, or it can be a server token, which has access to all user data.
+ Headers
x-tidepool-session-token : 23sadf87.123840.aasd90JKj
+ Response 200
[
"profile", "groups", "private"
]
## Metadata Manipulation [/metadata/{userid}/{collection}]
The main metadata block of information is managed here. Groups and Private have special endpoints.
### Create or update a metadata collection - also works with PUT [POST]
+ Parameters
+ collection (required, string, `profile`) ... A collection type from one of the registered types.
+ userid (required, string, `userid`) ... The userid for the user for whom this data is being stored.
+ Request
Body should contain the fields that should be updated. (Someday, the field names will be enforced by a schema).
Omitting a field will not remove it -- to delete a field, you must set its value to null.
+ Headers
x-tidepool-session-token : 23sadf87.123840.aasd90JKj
+ Body
{
"fullname": "Jonathan Livingston",
"shortname": "Jonny",
"publicbio": "I fly far and fast. T1D is something I have, not who I am.",
"image_url": "https://files.tidepool.io/87263b8476fad2836486af125/me.jpg",
}
+ Response 200
+ Response 404
### Retrieve a metadata collection [GET]
+ Parameters
+ collection (required, string, `profile`) ... A collection type from one of the registered types.
+ userid (required, string, `metaid`) ... The userid for the user for whom this data is being stored.
+ Request
+ Headers
x-tidepool-session-token : 23sadf87.123840.aasd90JKj
+ Response 200 (application/json)
{
"fullname": "Jonathan Livingston",
"shortname": "Jonny",
"publicbio": "I fly far and fast. T1D is something I have, not who I am.",
"image_url": "https://files.tidepool.io/87263b8476fad2836486af125/me.jpg",
}
+ Response 404
### Remove a metadata collection --NOT IMPLEMENTED-- [DELETE]
+ Parameters
+ collection (required, string, `profile`) ... A collection type from one of the registered types.
+ userid (required, string, `userid`) ... The userid for the user for whom this data is being stored.
+ Request
+ Headers
x-tidepool-session-token : 23sadf87.123840.aasd90JKj
+ Response 501
+ Response 204
+ Response 404
## Private Pair Manipulation [/metadata/private/{userid}/{name}]
If you get a pair that does not already exist, this call will create one and return it. If it already exists, you'll get that pair back again.
DELETE is spec'd but not implemented yet.
### Retrieve a private pair [GET]
+ Parameters
+ userid (required, string, `metaid`) ... The userid for the user for whom this data is being stored.
+ name (required, string, `sandcastle`) ... The name of the private pair. Any name is legal. Currently defined are patient, sandcastle.
+ Request
+ Headers
x-tidepool-session-token : 23sadf87.123840.aasd90JKj
+ Response 200 (application/json)
+ Body
{
id: "2423412",
hash: "69fd718d9aa9a487e6142e21"
}
+ Response 404
### Remove a group record --NOT IMPLEMENTED-- [DELETE]
+ Parameters
+ userid (required, string, `userid`) ... The userid for the user for whom this data is being stored.
+ name (required, string, `sandcastle`) ... The name of the private record. Any name is legal. Currently defined are patient, sandcastle.
+ Request
+ Headers
x-tidepool-session-token : 23sadf87.123840.aasd90JKj
+ Response 501
## User Data access for other users [/otheruser/publicinfo?users={useridlist}]
This call is used to fetch information about other users, but it only works if the users are either in your care team or your patient group.
The return from this call is always 200 if the request is proper, and the response body will indicate on a per-id basis
whether or not the data was available. The session token MUST be a user token (not a server token).
### Retrieve public userdata for one or more related users [GET]
+ Parameters
+ useridlist (required, array of string, `a3a312bd,ac9312cf`) ... The set of userids for whom this data is being requested.
+ Request
+ Headers
x-tidepool-session-token : 23sadf87.123840.aasd90JKj
+ Response 200 (application/json)
[
{
"id": "a3a312bd",
"fullname": "Jonathan Livingston",
"shortname": "Jonny",
"publicbio": "I fly far and fast. T1D is something I have, not who I am.",
"image_url": "https://files.tidepool.io/87263b8476fad2836486af125/me.jpg",
},
{
"id": "ac9312cf",
"error": "Userid not accessible or not valid"
}
]
+ Response 401
## User Data access for other users [/otheruser/inmygroups?users={useridlist}]
This call is used to fetch information about which groups a set of users is in, relative to the logged-in user. Every ID is returned
even if invalid or unauthorized (these will return an empty groups list).
The session token MUST be a user token (not a server token).
### Retrieve public userdata for one or more related users [GET]
+ Parameters
+ useridlist (required, array of string, `a3a312bd,ac9312cf`) ... The set of userids for whom this data is being requested.
+ Request
+ Headers
x-tidepool-session-token : 23sadf87.123840.aasd90JKj
+ Response 200 (application/json)
[
{
"id": "a3a312bd",
"groups": ["careteam"]
},
{
"id": "ac9312cf",
"groups": []
}
]