linksColl api design

[heymind]

/** 
 * ========== HTTP API ==========
 *  *tokenAuth* : in request header
 *                authorization: <user's token here>
 * 
 *  ALL POST,PUT requests SHOULD put its params in body section 
 *  with 'application/json' content-type
 *  ALL GET requests SHOULD put its params in query string
 * 
 *  ALL requests that the server resolves correctly MUST have json 
 *  type response below. Called 'ok struct'
 *  { ok: Boolean,
 *    data: {......} // if ok is true
 *    error: { code: <option>, message: String } // if ok is false
 *  }
 * 
 *  Bulk requests [<request payload 1>,<request payload 2>,....<request payload n>]
 *  will be reponsed like [<ok struct 1>, <ok struct 2>,.....<ok struct n>]
 * 
 *  NOTES: 
 *      401: endpoints required tokenAuth but request's token is invalid 
 *      400: lack of necessary params
 * ==============================
 */

LINKS COLLECTION

GET /v1/linksColl/:id

request

• id (required)

response

• linksColl with all its items

GET /v1/linksColl/own

return all linksColls that the current user has created

request

• perCollItemLimit
  • 0 -> return all items
  • n -> n items
  • undefined -> only return metas (default)

response

• [linksColl]

GET /v1/linksColl/watch

return all linksColls that the current user watches

request

• perCollLimit
• itemUpdatedAfter like a small notif red point

reponse

• [linksColl]

GET /v1/linksColl/query

requests

• title,description,tag,category fuzz search
• readers,watchers,collaborators = user's _id
• author = user's _id
• updatedAter = time
• perCollItemLimit
• sortBy = |title,description,tag,category| updatedTime createdTime hot
• limit
• page

response

• [linksColl]

POST /v1/linksColl

create a linksColl without items

requests

• title (required) ,description,tags(array),category (required)
• readers,watchers,collaborators (default:creator)

response

• linksColl

PUT /v1/linksColl
create a linksColl without items

requests

• _id (required)
• title,description,category

response

• linksColl

DELETE /v1/linksColl (not possible)

POST/DELETE /v1/linksColl/:id/tags/(:tagName)

modify tags

GET/POST/PUT/DELETE /v1/linksColl/:id/[readRequests,readers,watchers,collaborators]/(:id)

LINKS COLLECTION ITEM

GET POST /v1/linksColl/:id/links

response

• [linksColl item]

POST /v1/linksColl/:id/links/(bulk)

request

• title (required),tags,category (required),isPublished,url (required)

response

• [linksColl item]

PUT /v1/linksColl/:id/links/(bulk)

request

• _id (required)
• title,tags,category,isPublished,url

response

• [linksColl item]

DELETE /v1/linksColl/:id/links/(bulk)

request

• _id (required)

#todo

• 权限界定
• 不同场景下的返回内容
  比如说 在query接口中只返回ReadersCount而不是所有等等

@dimpurr