· 9 years ago · Aug 22, 2016, 06:56 AM
1API endpoints
2-------------
3+ **[/auth/](#auth)**
4+ **[/api/user/](#user)**
5+ **[/api/media/](#media)**
6+ **[/api/discover/](#discover)**
7+ **[/api/message/](#message)**
8+ **[/api/notification/](#notification)**
9
10Common Data Structure
11------------------------
12__{profile}__ user's public profile
13* _id
14* name
15* username
16* avatar
17 * small: url string, used in most places
18 * large: url string, used in user's home page
19* details
20 * slogan
21 * intro
22 * hashtags
23 * organization
24 * region
25 * email (default is private, user can choose to public it, may not same as account email)
26 * phone (default is private, user can choose to public it)
27 * address (default is private, user can choose to public it)
28* stats
29
30user stats:
31* images: number
32* videos: number
33* models: number (unused currently)
34* albums: number
35* followers: number
36* followings: number
37
38__{profileSelf}__ user's self profile, including all necessary fields, only him/herself can see
39* _id
40* name
41* username
42* email
43* avatar
44 * small: url string, used in most places
45 * large: url string, used in user's home page
46* details
47 * slogan
48 * intro
49 * hashtags
50 * organization
51 * region
52 * email
53 * phone
54 * address
55 * location
56* stats
57* role
58
59__{profileBasic}__ user's basic profile, displayed in name card (like the ones in feeds page), or search results etc.
60* _id
61* name
62* username
63* avatar
64 * small: url string, used in most places
65 * large: url string, used in user's home page
66
67__{media}__ media info
68* _id
69* author: {profileBasic}
70* description: string
71* hashtags: array, like ['#aaa', '#bbb', '#ccc']
72* stats
73* status: one of 'normal', 'pending', 'error', 'deleted'
74* type: one of 'image', 'video', 'model'
75* thumbnail
76 * small: url string, used on mobile device; for video, this is an url array
77 * large: url string, used on big screen device; for video, this is an url array
78* url
79 * small: url string, used on mobile device and desktop
80 * large: url string, for desktop fullscreen
81
82media stats:
83* likes: number
84* favors: number
85* shares: number
86* comments: number
87* views: number
88
89for media status:
90* 'normal' means everything is ok
91* 'pending' means media is under processing, thumbnail is available, url is not
92* 'error' means something wrong happens, thumbnail and url may not available, should delete it
93* 'deleted' means media been deleted, client side should never receive such media
94
95Pagination
96----------
97All GET apis that return array will be paginated.
98
99Pagination Parameter:
100* from: number or an id, next page will start from here (exclusive), optional
101* limit: number, maximal results returned, optional
102
103Return Format
104--------------
105All APIs return JSON data with status 200, or empty with status 204, or error
106
107error format:
108* status: status code
109* msg: a msg explains the error, can be displayed directly
110
111
112/auth/
113------
114
115__POST__ /auth/local
116auth local user, after successful auth, token will be set in cookie, also returned. following api calls can be authed by Authorization header or access_token query parameter
117
118Body Parameter
119* email
120* password
121
122Response
123* token: access token for following api calls
124* config: config for firebase(or wilddog), including token, url
125
126__GET__ /auth/facebook/
127auth user with facebook login
128
129__GET__ /auth/facebook/callback
130set token cookie
131
132Query Parameter
133* code
134
135__GET__ /auth/twitter/
136auth user with twitter login
137
138__GET__ /auth/twitter/callback
139set token cookie
140
141Query Parameter
142* oauth_token
143* oauth_verifier
144
145__GET__ /auth/google/
146auth user with google login
147
148__GET__ /auth/google/callback
149set token cookie
150
151Query Parameter
152* oauth_token?
153* oauth_verifier?
154
155/user/
156------
157
158__POST__ /api/user/
159create user account
160
161Body Parameter
162* name
163* email
164* password
165* hashtags
166* intro (optional)
167* hashtags (optional)
168* address (optional)
169* phone (optional)
170
171Response
172* token: token string
173
174__DELETE__ /api/user/
175delete user account
176
177Body Parameter
178* id: user id
179
180Response
181* null
182
183
184__GET__ /api/user/profile
185get user profile
186
187Query parameter
188* id: user id, optional, default is current user (req.user._id)
189
190Response
191* {profile} or {profileSelf}
192
193__POST__ /api/user/profile
194update user profile
195
196Body Parameter
197* {profile}: partial fields, only those changed
198
199Response
200* {profile}: new profile
201
202
203__POST__ /api/user/follow
204follow a user
205
206Body Parameter
207* id: user id of the other user
208
209Response
210* null
211
212__POST__ /api/user/unfollow
213unfollow a user
214
215Body Parameter
216* id: user id of the other user
217
218Response
219* null
220
221__POST__ /api/user/block
222block a user
223
224Body Parameter
225* id: user id of the other user
226
227Response
228* null
229
230__POST__ /api/user/unblock
231unblock a user
232
233Body Parameter
234* id: user id of the other user
235
236Response
237* null
238
239__GET__ /api/user/followers
240get user's followers
241
242Body Parameter
243* id: user id, optional, default is current user
244* from: user id or number
245* limit: number
246
247Response
248* [{profileBasic}]: array of users
249
250__GET__ /api/user/followings
251get users that a user is following
252
253Body Parameter
254* id: user id, optional, default is current user
255* from: user id or number
256* limit: number
257
258Response
259* [{profileBasic}]: array of users
260
261__POST__ /api/user/password
262set user's new password
263
264Body Parameter
265* oldPassword: old password
266* newPassword: new password
267
268Response
269* null
270
271__POST__ /api/user/setting
272update user setting
273
274Body Parameter
275* {setting}: partial fields, only those changed
276
277Response
278* {setting}: new setting
279
280/media/
281-------
282__GET__ /api/media/
283get media. if id specified, all other parameters will be discarded, return a single media with that id; if userId specified, return medias of that user
284
285Query Parameter
286* id: media id, if specified, omit all other parameters
287* userId: user id
288* from: media id or number
289* limit: number
290
291Response
292* {media} or [{media}]
293
294__DELETE__ /api/media/
295delete a media
296
297Body Parameter
298* id: media id
299
300Response:
301* null
302
303__POST__ /api/media/upload
304upload media
305
306Body Parameter
307* type: upload type, must be one of "image", "video", "model"
308* description: description of the media
309* hashtags: hashtags, auto detected tags or user input
310* location: media location, obtained from media exif info or user input
311
312Response
313* {media}: newly created media
314
315__POST__ /api/media/update
316update media
317
318Body Parameter
319* {media}: partial fields, only those changed
320
321Response
322* {media}: updated media
323
324__POST__ /api/media/like
325like a media
326
327Body Parameter
328* id: media id
329
330Response
331* null
332
333__POST__ /api/media/unlike
334unlike a media
335
336Body Parameter
337* id: media id
338
339Response
340* null
341
342__POST__ /api/media/favor
343favor a media
344
345Body Parameter
346* id: media id
347
348Response
349* null
350
351__POST__ /api/media/unfavor
352unfavor a media
353
354Body Parameter
355* id: media id
356
357Response
358* null
359
360__GET__ /api/media/comments
361get comments of a media
362
363Query Parameter
364* id: media id
365* from: comment id or number
366* limit: number
367
368Response
369* [{comment}]: array of comments on the media
370
371__POST__ /api/media/comment
372comment on a media
373
374Body Parameter
375* content: comment content
376
377Response
378* {comment}: the new comment
379
380
381__DELETE__ /api/media/comment
382delete a comment on a media, only user self can
383
384Body Parameter
385* id: comment id
386
387Response
388* null
389
390__POST__ /api/media/tagging
391auto detect tags from media, works only for image
392
393Body Parameter
394* data: dataURI in base64 form
395
396Response
397* [{autotag}]
398
399media autotag
400* name: string
401* confidence: number, how sure image qualifies this tag
402
403/discover/
404----------
405__GET__ /api/discover
406discover (search/recommend) user and/or media
407
408Query Parameter
409* type: 'user' or 'media', return both if not specified or not these two values
410* q: query string, optional, if specified, return search results; otherwise return recommended results
411* name: name of user
412* hashtags: hashtags of user/media
413* description: description of media
414* author: name of media author
415* from: id (not user id or media id, it's the id generated by elasticsearch)
416* limit: number
417
418user may do fields search by typing 'restaurant #newyork description:Japanese' in search input, which specifies a search of 'restaurant' that has '#newyork' hashtag and 'Japanese' in description. this is equivalent to q=restaurant&hashtags=#newyork&description=Japanese
419
420Response
421* [{profileBasic|media}]
422
423NOT FINISHED
424-------------------------
425__GET /api/discover/feed
426get feed for current user
427
428Query Parameter
429* type: 'timeline', 'user', 'notification'
430* from: id (not user id or media id, generated by stream)
431* limit: number
432
433Response
434* [{activity}]
435
436__{activity}__ feed activity
437* actor: user that triggered this activity
438* id: id of this activity, for paging use
439* verb: 'post', 'like', 'share', 'comment', 'follow', etc.
440* media: {media}
441* user: {profile}
442
443/message/
444----------
445When user logged in, a firebase access token is returned, messages can be retrieved directly from firebase using this token. New messages are automatically sent from firebase via web socket.
446Two users can send messages to each other in a chat room. Group chat is not supported. User will receive new msg alert if he/she is not in the chat room.
447
448__POST__ /api/message/
449create or reuse a chat room for current user and user with userId
450
451Body Parameter
452* userId: id of the other user
453
454Response
455* roomId: chat room id
456
457__DELETE__ /api/message/
458user indicates to delete a chat room. Chat room will be deleted only if both users have indicated to do so. If one user did so, a marker will be stored in firebase database, he/she will no long see message history with same the other user even if he/she or the other user continues the conversation, but the other user is not affected.
459
460Body Parameter
461* roomId: chat room id
462
463
464/notification/
465-------------
466When user logged in, a firebase access token is returned, notifications can be retrieved directly from firebase using this token. New notifications are automatically sent from firebase via web socket.
467
468__POST__ /api/notification/mute
469mute a notification
470
471Body Parameter
472* id: notification id
473
474Response
475* null
476
477__POST__ /api/notification/markRead
478mark a notification read
479
480Body Parameter
481* id: notification id
482
483Response
484* null
485
486__DELETE__ /api/notification/
487delete a notification
488
489Body Parameter
490* id: notification id
491
492Response
493* null