apidoc.raml 11KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446
  1. #%RAML 1.0
  2. ---
  3. title: ditup.org REST
  4. baseUri: https://api.ditup.org/{version}
  5. version: v1
  6. mediaType: application/vnd.api+json
  7. types:
  8. User:
  9. properties:
  10. type:
  11. enum: [users]
  12. id:
  13. type: string
  14. attributes:
  15. properties:
  16. givenName:
  17. familyName:
  18. description:
  19. location:
  20. email:
  21. Tag:
  22. properties:
  23. type:
  24. enum: [tags]
  25. id:
  26. type: string
  27. /users:
  28. get:
  29. description: |
  30. The following data can be received:
  31. - new users: `?sort=-created&page[offset]=0&page[limit]=5`
  32. - users with my tags `?filter[byMyTags]`
  33. - users by tags `?filter[tag]=tag1,tag2,tag3` TODO rename
  34. - new users with my tags: `?sort=-created&filter[withMyTags]=2&page[offset]=5&page[limit]=3`
  35. - users within a rectangle: `?filter[location]=-1.0,-1.0,1.0,1.0`
  36. queryParameters:
  37. filter?:
  38. properties:
  39. tag?:
  40. type: string
  41. description: a comma separated list of tags to search by
  42. byMyTags?:
  43. type: nil
  44. description: perform a search by tags which i (logged user) have
  45. withMyTags?:
  46. type: integer
  47. description: Amount of tags which found users should have in common with me. Used in connection with sort=-created
  48. location?:
  49. type: string
  50. description: A rectangle to search within - `southWestLatitude,southWestLongitude,northEastLatitude,northEastLongitude`.
  51. sort?:
  52. description: if sort=-created is specified, new users will be returned
  53. enum:
  54. - '-created'
  55. page?:
  56. description: support for pagination
  57. properties:
  58. offset:
  59. type: integer
  60. description: offset of the documents to return (which is the first document to return?)
  61. limit:
  62. type: integer
  63. description: amount of documents to return
  64. responses:
  65. 200:
  66. 400:
  67. post:
  68. description: Create a new user with unverified email. Verification message will be sent to the provided email.
  69. body:
  70. example:
  71. data:
  72. type: users
  73. attributes:
  74. username: user1
  75. email: user1@example.com
  76. password: correcthorsebatterystaple
  77. responses:
  78. 201:
  79. description: Success.
  80. body:
  81. example:
  82. data:
  83. type: users
  84. id: user1
  85. attributes:
  86. username: user1
  87. givenName:
  88. familyName:
  89. description:
  90. location:
  91. 400:
  92. description: Validation error.
  93. 409:
  94. description: Conflict. Username must be unique.
  95. /{username}:
  96. get:
  97. responses:
  98. 200:
  99. # examples:
  100. # - notLogged:
  101. # data:
  102. # type: users
  103. # id: user1
  104. # - logged:
  105. # data:
  106. # type: users
  107. # id: user1
  108. # attributes:
  109. # givenName: name
  110. # familyName:
  111. # description: this is a description
  112. # location:
  113. # - loggedAsSelf:
  114. # data:
  115. # type: users
  116. # id: user1
  117. # attributes: # TODO
  118. 404:
  119. description: User doesn't exist.
  120. patch:
  121. description: Edit user profile (givenName, familyName, description, location).
  122. responses:
  123. 200:
  124. 403:
  125. 400:
  126. /avatar:
  127. get:
  128. description: Get an avatar image of an user. Specifying size is supported.
  129. queryParameters:
  130. filter?:
  131. properties:
  132. size:
  133. description: Return avatar of a specified size.
  134. enum:
  135. - 16
  136. - 32
  137. - 64
  138. - 128
  139. - 256
  140. - 512
  141. responses:
  142. 200:
  143. body:
  144. image/svg+xml:
  145. description: Default Identicon.js image.
  146. image/jpeg:
  147. description: Image provided by user.
  148. 403:
  149. 404:
  150. patch:
  151. description: Upload avatar image. Maximum size is 2MB.
  152. body:
  153. multipart/form-data:
  154. description: |
  155. Supported image types:
  156. - jpeg
  157. - png
  158. responses:
  159. 200:
  160. 400:
  161. 403:
  162. # TODO: delete
  163. /tags:
  164. get:
  165. description: Get a list of user's tags (with story and relevance).
  166. responses:
  167. 200:
  168. # TODO 403:
  169. # TODO 404:
  170. post:
  171. description: Add a tag to self and specify story and relevance.
  172. responses:
  173. 201:
  174. 400:
  175. 403:
  176. 404:
  177. 409:
  178. /{tagname}:
  179. get:
  180. description: Show a tag and user's story and relevance.
  181. responses:
  182. 200:
  183. # TODO!!! 403, 404
  184. patch:
  185. description: Update user's story and/or relevance to a tag.
  186. responses:
  187. 200:
  188. 400:
  189. 403:
  190. 404:
  191. delete:
  192. description: Remove a tag from a user.
  193. responses:
  194. 204:
  195. 403:
  196. 404:
  197. /auth:
  198. /token:
  199. get:
  200. description: Send Basic auth header and receive JWT token.
  201. responses:
  202. 200:
  203. body:
  204. example:
  205. meta:
  206. token: aaa.bbb.ccc
  207. 401:
  208. /exp:
  209. get:
  210. description: Get time till a provided token's expiration [seconds].
  211. responses:
  212. 200:
  213. body:
  214. example:
  215. meta:
  216. exp: 3600
  217. 403:
  218. # TODO JWT Token
  219. # send Basic auth header and receive JWT token
  220. # check validity of a given JWT token
  221. # remove basic auth
  222. /account:
  223. patch:
  224. description: |
  225. The following actions are supported:
  226. - send email with code for resetting forgotten password
  227. - reset forgotten password with reset code
  228. - update unverified email and send verification link
  229. - verify email
  230. - change password
  231. queryParameters:
  232. reset-password?:
  233. type: nil
  234. description: Send email with code for resetting forgotten password
  235. /contacts:
  236. get:
  237. description: |
  238. Show trust and reference which user gave or received.
  239. Don't show unconfirmed contacts to 3rd users.
  240. Don't show trust and reference to user who received contact request and didn't confirm, yet.
  241. queryParameters:
  242. filter:
  243. properties:
  244. from?:
  245. type: string
  246. description: Read contacts given by the specified user.
  247. to?:
  248. type: string
  249. description: Read contacts given to the specified user.
  250. post:
  251. description: Create a contact request.
  252. responses:
  253. 201:
  254. 400:
  255. 403:
  256. 404:
  257. 409:
  258. /{from}/{to}:
  259. get:
  260. description: |
  261. Show a contact between two users including reference and trust given by `:from` to `:to`
  262. - the requester should see unconfirmed contact including message
  263. - the requested should see only the message of the unconfirmed contact
  264. - every other logged user can see only confirmed contacts (trust and reference)
  265. patch:
  266. description: |
  267. The following actions are supported:
  268. - confirm a contact request
  269. - update a contact from self
  270. responses:
  271. 200:
  272. 400:
  273. 403:
  274. 404:
  275. delete:
  276. description: Delete a contact.
  277. /messages:
  278. post:
  279. description: Create a new message to another user.
  280. get:
  281. description: |
  282. The following information can be retrieved:
  283. - messages with another user
  284. - threads
  285. - amount of threads with unread messages
  286. queryParameters:
  287. filter:
  288. properties:
  289. count:
  290. description: Show amount of unread threads.
  291. type: nil
  292. threads:
  293. description: Show last messages of my threads sorted by time.
  294. type: nil
  295. with:
  296. type: string
  297. description: Show messages with the given user from newest to oldest.
  298. responses:
  299. 200:
  300. 403:
  301. 404:
  302. # TODO 400
  303. /{id}:
  304. patch:
  305. description: Set `read` to `true` on the message and all the previous unread messages.
  306. responses:
  307. 200:
  308. 403:
  309. /tags:
  310. get:
  311. description: |
  312. The following data can be received
  313. - tags with names similar to a given string (similarity = one of the words in tagname starts with the given string) (`?filter[tagname][like]=fraction-of-tag-name`)
  314. - tags related to my tags `?filter[relatedToMyTags]`
  315. - tags related to given tags `?filter[relatedToTags]=tag1,tag2,tag3`
  316. - random tags `?filter[random]`
  317. - popular tags by amount of uses `?sort=-popularityByUses`
  318. TODO: new tags (which have some uses)
  319. queryParameters:
  320. filter?:
  321. properties:
  322. tagname:
  323. properties:
  324. like:
  325. type: string
  326. relatedToMyTags:
  327. type: nil
  328. relatedToTags:
  329. description: a comma separated list of tags to search from
  330. type: string
  331. random:
  332. type: nil
  333. sort?:
  334. description: if sort=-popularityByUses is specified, popular tags will be returned
  335. enum:
  336. - '-popularityByUses'
  337. responses:
  338. 200:
  339. 400:
  340. 403:
  341. post:
  342. description: Create a new tag.
  343. responses:
  344. 201:
  345. 400:
  346. 403:
  347. 409:
  348. /{tagname}:
  349. get:
  350. description: Read a tag.
  351. responses:
  352. 200:
  353. 404:
  354. /ideas:
  355. post:
  356. description: Create a new idea.
  357. responses:
  358. 201:
  359. 400:
  360. 403:
  361. get:
  362. description: |
  363. Get a list of ideas
  364. - ideas with my tags: `?filter[withMyTags]`
  365. - ideas with provided tags: `?filter[withTags]=tagname0,tagname1,tagname2`
  366. - new ideas: `?sort=-created`
  367. - ideas with provided creators: `?filter[creators]=username0,username1,username2`
  368. - ideas commented by provided users: `?filter[commentedBy]=username0,username1,username2`
  369. - highly voted ideas with minimum amount of votes parameter: `?filter[highlyVoted]=bottomValueLimit`
  370. - trending ideas: `?filter[trending]`
  371. /{id}:
  372. get:
  373. description: Read an idea by id.
  374. responses:
  375. 200:
  376. 400:
  377. 403:
  378. 404:
  379. patch:
  380. description: |
  381. Update an idea (title, detail).
  382. Currently only creator is authorized to do that.
  383. response:
  384. 200:
  385. 400:
  386. 403:
  387. 404:
  388. /tags:
  389. post:
  390. description: Add tag to idea.
  391. responses:
  392. 201:
  393. 400:
  394. 403:
  395. 404:
  396. 409:
  397. get:
  398. description: Get tags of idea.
  399. responses:
  400. 200:
  401. 400:
  402. 403:
  403. 404:
  404. /{tagname}:
  405. delete:
  406. description: Remove tag from idea.
  407. responses:
  408. 204:
  409. 400:
  410. 403:
  411. 404:
  412. /comments:
  413. post:
  414. description: Create a comment for an idea.
  415. responses:
  416. 201:
  417. 400:
  418. 403:
  419. 404:
  420. get:
  421. /votes:
  422. post:
  423. description: Vote for an idea.
  424. responses:
  425. 201:
  426. 400:
  427. 403:
  428. 404:
  429. /comments:
  430. /{id}:
  431. patch:
  432. delete:
  433. /reactions:
  434. post:
  435. get:
  436. /reactions:
  437. /{id}:
  438. patch:
  439. delete: