-
Notifications
You must be signed in to change notification settings - Fork 0
/
API.yaml
481 lines (414 loc) · 12.8 KB
/
API.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
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
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
##############################################################################
Data models:
- UserProfile:
Fields:
- user
- firstName
- middleName
- lastName
- gender:
Type: String ['male', 'female', 'undisclosed']
- pseudonyms:
Type: List of Strings
- birthDay
- publicEnabled
- defaultPermit:
Type: Reference to Permit
Description: >
Shortcut to the default Permit to minimize the number of Datastore queries.
- publicPermit
Type: Reference to Permit
Description: >
Shortcut to the public Permit to minimize the number of Datastore queries.
- defaultGroup
# - nationality?
# - namesday?
- UserSettings:
Parent: UserProfile
Fields:
- disablePublicProfiles:
Type: Boolean
- preferredLanguage:
Type: String
- notifyNewsletter:
Type: Boolean
- notifyEmails:
Type: Boolean
- cardDAVenabled:
Type: Boolean
- Psinque:
Description: >
Unilateral contact data synchronization channel. The parent is always the
Contact of the receiving user (the data beneficient). Such a contact will
always exists (in contrast to the contact data source, which will not have
a Contact created if the Psinque is public).
Parent: Contact
Fields:
- private:
Description: >
Determines whether this Psinque feeds on private or public data.
Type: Boolean
- permit:
Type: Reference to Permit
Description: >
"A reference to the friend's Permit entity that holds the vCard. In case"
- fromUser
- creationTime
- status:
Description: "'pending', 'established' or 'banned'"
- Contact:
Description: A contact consisting of an incoming and an outgoing psinque.
Parent: UserProfile (destination of the Psinque)
Fields:
- incoming
- outgoing
- friend:
Description: UserProfile of the friend, who is represented by this Contact.
Type: Reference to UserProfile
- group:
Description: Group to which the contact belongs.
Type: Reference to Group
- permit:
Description: Permit to which the contact belongs.
Type: Reference to Permit
- Permit:
Description: >
"A set of permissions to view user's data. There is exactly one default
private Permit, exactly one public Permit and an unlimited number of private
groups. The public Permit has an option that disables it. No Contacts can
be added to the public Permit, but when the outgoing Psinques are removed,
they are added there automatically."
Parent: UserProfile
Fields:
- name
- canViewName
- canViewBirthday
- canViewGender
- public:
Type: Boolean
- vcard:
Description: >
Cached vCard that is being updated every time there is a change
to the permissions for a particular set of groups.
- vcardMTime:
Description: Modification timestamp for the vCard, used for etags.
- vcardMD5:
Description: MD5 checksum calculated for the vCard, used for etags.
- displayName:
Description: Cached display name for all contacts with this permit.
- Group:
Description: A group of Contacts (or, in fact, incoming Psinques).
Parent: UserProfile
Fields:
- name
- sync:
Type: Boolean
Description: If False, this group will not sync to the phone/gmail/facebook.
- UserEmail:
Parent: UserProfile
Fields:
- email
- emailType
- primary:
Type: Boolean
Description: >
True if this is the primary email address. The primary email is used
for notifications.
- PermitEmail:
Parent: Permit
Fields:
- userEmail
- canView:
Type: Boolean
- UserIM:
Parent: UserProfile
- PermitIM
Parent: Permit
Fields:
- imAddress
- canView:
Type: Boolean
- UserAddress:
Parent: UserProfile
- PermitAddress
Parent: Permit
Fields:
- physicalAddress
- canView:
Type: Boolean
- UserWWW:
Parent: UserProfile
- PermitWWW
Parent: Permit
Fields:
- internetAddress
- canView:
Type: Boolean
- UserPhone:
Parent: UserProfile
- PermitPhone
Parent: Permit
Fields:
- phoneNumber
- canView:
Type: Boolean
- CardDAVPassword
Description: >
A pair of username/password for accessing the CardDAV server.
Parent: UserProfile
Fields:
- generatedUsername
- generatedPassword
##############################################################################
Pages:
#-----------------------------------------------------------------------------
- My card:
URL: /mycard/*
Views: # return HTML
- view: Displays the contact details edit form.
Actions: # return JSON, used for AJAX and as API for external apps
- updategeneral: Updates the singular contact details (names, birthday, gender)
- addemail:
Description: Adds a new email entry.
Parameters:
- email
- type
Action flow:
- Create a new UserEmail with UserProfile as a parent.
- Set 'email' and 'emailType'.
- addim
- addwww
- addphone
- updateemail:
Parameters:
- key
- email
- type
- updateim
- updatewww
- updatephone
- removeemail
- removeim
- removewww
- removephone
- enablepublic:
Description: Enables or disables the public permit.
Parameters:
- enable:
Type: Boolean
#-----------------------------------------------------------------------------
- Permits:
URL: /permits/*
Views:
- view: Displays the list of existing Permits.
Actions:
- removepermit:
Parameters:
- key
Returns: null
Action flow:
- Find all Contacts that use this Permit and change their 'permit' to 'Default'.
- Remove all Permission* children.
- Remove the Permit.
- addpermit:
Parameters:
- name
Returns:
- key:
Description: Datastore key of the new permit.
Action flow:
- Creates a new Permit entity, with all Permission* children.
- "Generate the Permit's vCard and etag."
- setgeneralpermit:
Description: >
The permissions need to be set separately for each element of the
user profile, because of their unbounded number.
Action flow:
- Get and modify the Permit entity.
- "Update the Permit's vCard and etag."
Parameters:
- key:
Description: Datastore key of the Permit* entity.
- canViewName:
Description: In case of type = general.
- canViewBirthday:
Description: In case of type = general.
- canViewGender:
Description: In case of type = general.
- canView:
Description: In case of type != general.
- setemailpermit:
Action flow:
- Get and modify the PermitEmail entity.
- "Update the Permit's vCard and etag."
Parameters:
- key
- canView
#-----------------------------------------------------------------------------
- Psinques:
URL: /psinques/*
Views:
- view:
Description: Displays the lists of Contacts and Psinques.
Parameters:
- offset
- cursor
- viewdecision:
Description: >
Display the state of a decision (for a pending Psinque).
This is a page displayed after the user clicks a link
received in an email.
Parameters:
- key:
Description: Datastore key of the pending Psinque.
Actions:
- searchemail:
Description: >
Searches for a user with a particular email address registered in the system.
Parameters:
- email
Returns:
- key:
Description: "Datastore key to the other person's UserProfile."
- publicEnabled:
Description: True if the other user has enabled the public profile.
Action flow:
- Search for the owner of the email address.
- Check if a Psinque from that user to the current user already exists.
- Check if the user has the public profile enabled.
- acceptrequest:
Description: Accepts a request to share private data.
Parameters:
- key: datastore key of the pending Psinque.
Returns:
- key: datastore key to the newly created Contact.
Action flow:
- Search for existing Contacts on both sides of the Psinque.
- "If contactIn.incoming points to an existing Psinque, raise error if it's a private Psinque and replace it with the accepted Psinque otherwise; remove the old Psinque"
- Add new Psinque as 'outgoing' in that Contact.
- Set the status of the Psinque to "established".
- rejectrequest:
Description: See 'acceptrequest'.
- banrequest:
Description: See 'acceptrequest'.
- changepermit:
Description: Assigns a Contact a new Permit.
Parameters:
- contact: datastore key of the Contact.
- permit: datastore key of the Permit.
Action flow:
- Change 'permit' of the Contact.
- changegroup:
Description: Assigns a Contact a new Group.
Parameters:
- contact: datastore key of the Contact.
- group: datastore key of the Group.
Action flow:
- Change 'group' of the Contact.
- removeincoming:
Description: Removes the incoming Psinque for a given Contact.
Parameters:
- key: datastore key of the Contact.
Action flow:
- Get the Contact.
- Obtain the incoming Psinque from Contact.incoming.
- Obtain the Contact on the other end of it.
- Clear the 'incoming' field for this Contact.
- If 'outgoing' is empty, remove this Contact.
- If the Psinque was private:
- Obtain the friend's Contact that has this Psinque as 'outgoing'.
- Clear the 'outgoing' field for friend's Contact.
- If 'incoming' in friend's Contact is empty, remove friend's Contact.
- If enabled, notify the friend about this fact.
- removeoutgoing:
Description: >
"Removes the outgoing Psinque for a given Contact. If the current user
has a public group, the Psinque is downgraded to public. If there's
no public group."
Parameters:
- key: datastore key of the Contact.
Action flow:
- Get the Contact.
- Obtain the outgoing Psinque from Contact.outgoing.
- Clear the 'outgoing' field for this Contact.
- If 'incoming' is also empty, remove this Contact.
- Downgrade the Psinque to 'public'.
- If enabled, notify the friend.
- removecontact:
Description: >
Removes both the incoming and the outgoing Psinque and
then the Contact.
Parameters:
- key: datastore key of the Contact.
Action flow:
- Find friend's Contact.
- Remove incoming Psinque.
- Remove Contact.
- Clear the 'outgoing' field in friend's Contact.
- Set the outgoing Psinque's 'private' field to False.
- If enabled, notify friend that he's been downgraded to public.
- requestupgrade:
Description: >
Sends a request to a person from a Contact list to share his/her
private profile. There already must exist a Contact with a public
incoming Psinque.
Parameters:
- key:
Description: datastore key of the Contact.
Action flow:
- "Create a new Psinque with this Contact as parent, but don't assign it to the Contact's 'incoming' field until the decision is made."
- If the Contact only has the public Permit, change the Permit to the default private Permit (we need to share our data in order to get private data from our friend).
- If enabled, notify the user 'fromUser'.
- addpublic:
Description: "Adds the person's public profile as a new Contact."
Parameters:
- key:
Description: Datastore key of the other person's UserProfile.
Action flow:
- Check if a Psinque already exists.
- Create a new Contact and a new Psinque between the two contacts.
- addprivate:
Description: "Asks for a person's private profile and create a new Contact."
Parameters:
- key:
Description: >
"Datastore key of the other person's UserProfile or of a Contact
that has this person's UserProfile as a friend."
Action flow:
- "Check if a Psinque already exists; if it's public, run 'requestupgrade'."
- "Create a new Contact and a new public Psinque from the friend, then run 'requestupgrade'".
- If enabled, notify the other user.
#-----------------------------------------------------------------------------
- Settings:
URL: /settings/*
Views:
- view
Actions:
- generatecarddavlogin:
Parameters:
- name
Returns:
- username
- password
- deletecarddav:
Description: Removes an old CarDAVLogin entity.
Parameters:
- key
- updatesettings:
Parameters:
- language
- synccarddav
- notifyNewsletter
- notifyEmails
- notifyStopsUsingMyPrivateData
- notifyAsksForPrivateData
- notifyAllowsMePrivateData
- notifyDisallowsMePrivateData
- notifyRequestDecision
##############################################################################
Notifications:
- When someone stops using my private data.
- When someone asks me for accessing my private data.
- When someone adds me to his private group. (?)
- When my request for private data is accepted/rejected/banned.
- When someone revokes the permission to access his/her private data.