Mirror of the MieuxVoter API specifications. https://api.mieuxvoter.fr
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

650 lines
18 KiB

  1. # Warning: this file has been automatically generated. All manual modifications will be lost, see README.md for details.
  2. openapi: 3.0.0
  3. info:
  4. title: Mieux Voter
  5. description: A poll application based on Majority Judgment.
  6. version: 1.0.1-oas3
  7. termsOfService: 'https://github.com/MieuxVoter'
  8. contact:
  9. name: Mieux Voter app developpers team
  10. email: app@mieuxvoter.fr
  11. servers:
  12. - url: 'https://api.mieuxvoter.fr/v1'
  13. description: Main (production) server
  14. - url: 'https://sandboxapi.mieuxvoter.fr/v1'
  15. description: Internal staging server for testing
  16. paths:
  17. /polls:
  18. get:
  19. operationId: get-polls
  20. summary: Gets all polls.
  21. responses:
  22. '200':
  23. description: OK
  24. content:
  25. application/json:
  26. schema:
  27. type: array
  28. items:
  29. $ref: '#/components/schemas/poll'
  30. post:
  31. operationId: create-poll
  32. summary: Creates a poll.
  33. requestBody:
  34. required: true
  35. content:
  36. application/json:
  37. schema:
  38. $ref: '#/components/schemas/poll'
  39. responses:
  40. '201':
  41. description: Created
  42. content:
  43. application/json:
  44. schema:
  45. type: object
  46. properties:
  47. id:
  48. type: string
  49. description: Id of the created poll.
  50. links:
  51. get-poll:
  52. $ref: '#/components/links/get-poll'
  53. update-poll:
  54. $ref: '#/components/links/update-poll'
  55. delete-poll:
  56. $ref: '#/components/links/delete-poll'
  57. create-ballot:
  58. $ref: '#/components/links/create-ballot'
  59. list-poll-results:
  60. $ref: '#/components/links/list-poll-results'
  61. '400':
  62. description: Bad Request. Expect at least 2 proposals and a title.
  63. '/polls/{poll-id}':
  64. parameters:
  65. - in: path
  66. name: poll-id
  67. required: true
  68. schema:
  69. type: integer
  70. format: int64
  71. get:
  72. operationId: get-poll
  73. summary: Gets a poll by ID
  74. responses:
  75. '200':
  76. description: OK
  77. content:
  78. application/json:
  79. schema:
  80. $ref: '#/components/schemas/poll'
  81. '404':
  82. $ref: '#/components/responses/poll-not-found'
  83. patch:
  84. operationId: update-poll
  85. summary: Updates a poll
  86. requestBody:
  87. required: true
  88. content:
  89. application/json:
  90. schema:
  91. $ref: '#/components/schemas/poll'
  92. security:
  93. - {}
  94. - pollAuth: []
  95. responses:
  96. '200':
  97. description: OK
  98. content:
  99. application/json:
  100. schema:
  101. type: array
  102. items:
  103. $ref: '#/components/schemas/poll'
  104. delete:
  105. operationId: delete-poll
  106. summary: Deletes a poll
  107. responses:
  108. '200':
  109. description: OK
  110. '404':
  111. $ref: '#/components/responses/poll-not-found'
  112. security:
  113. - pollAuth: []
  114. '/polls/{poll-id}/ballots':
  115. parameters:
  116. - in: path
  117. name: poll-id
  118. required: true
  119. schema:
  120. type: string
  121. post:
  122. operationId: create-ballot
  123. summary: Creates a ballot
  124. requestBody:
  125. required: true
  126. content:
  127. application/json:
  128. schema:
  129. $ref: '#/components/schemas/ballot'
  130. security:
  131. - {}
  132. - participantAuth: []
  133. responses:
  134. '201':
  135. description: Created
  136. content:
  137. application/json:
  138. schema:
  139. type: object
  140. properties:
  141. id:
  142. type: string
  143. description: Id of the created ballot.
  144. links:
  145. get-ballot:
  146. $ref: '#/components/links/get-ballot'
  147. delete-ballot:
  148. $ref: '#/components/links/delete-ballot'
  149. '/polls/{poll-id}/ballots/{ballot-id}':
  150. parameters:
  151. - in: path
  152. name: poll-id
  153. required: true
  154. schema:
  155. type: string
  156. - in: path
  157. name: ballot-id
  158. required: true
  159. schema:
  160. type: string
  161. get:
  162. operationId: get-ballot
  163. summary: Gets a ballot by ID
  164. responses:
  165. '200':
  166. description: A ballot object
  167. content:
  168. application/json:
  169. schema:
  170. $ref: '#/components/schemas/ballot'
  171. delete:
  172. operationId: delete-ballot
  173. summary: Deletes a ballot
  174. responses:
  175. '200':
  176. description: OK
  177. '404':
  178. $ref: '#/components/responses/ballot-not-found'
  179. security:
  180. - participantAuth: []
  181. '/polls/{poll-id}/participants':
  182. parameters:
  183. - in: path
  184. name: poll-id
  185. required: true
  186. schema:
  187. type: string
  188. post:
  189. operationId: add-participant-to-poll
  190. description: Add a participant to a poll
  191. requestBody:
  192. content:
  193. application/json:
  194. schema:
  195. $ref: '#/components/schemas/participant'
  196. responses:
  197. '200':
  198. description: Invitation was sent
  199. content:
  200. text/plain:
  201. schema:
  202. type: string
  203. '404':
  204. $ref: '#/components/responses/poll-not-found'
  205. '/polls/{poll-id}/participants/{participant-id}/':
  206. parameters:
  207. - in: path
  208. name: participant-id
  209. required: true
  210. schema:
  211. type: string
  212. get:
  213. operationId: get-poll-participant
  214. summary: Get a participant from a poll
  215. responses:
  216. '200':
  217. description: OK
  218. content:
  219. application/json:
  220. schema:
  221. $ref: '#/components/schemas/participant'
  222. '404':
  223. $ref: '#/components/responses/participant-not-found'
  224. security:
  225. - {}
  226. - pollAuth: []
  227. delete:
  228. operationId: delete-poll-participant
  229. summary: Delete a participant from a poll
  230. responses:
  231. '200':
  232. description: OK
  233. '404':
  234. $ref: '#/components/responses/participant-not-found'
  235. security:
  236. - pollAuth: []
  237. '/polls/{poll-id}/results':
  238. parameters:
  239. - in: path
  240. name: poll-id
  241. required: true
  242. schema:
  243. type: string
  244. get:
  245. operationId: get-poll-results
  246. description: Get results of a poll
  247. responses:
  248. '200':
  249. description: OK
  250. content:
  251. text/plain:
  252. schema:
  253. $ref: '#/components/schemas/result'
  254. '404':
  255. $ref: '#/components/responses/poll-not-found'
  256. /users:
  257. get:
  258. operationId: get-users
  259. summary: Gets all users.
  260. responses:
  261. '200':
  262. description: OK
  263. content:
  264. application/json:
  265. schema:
  266. type: array
  267. items:
  268. $ref: '#/components/schemas/user'
  269. post:
  270. operationId: create-user
  271. summary: Creates an user
  272. requestBody:
  273. required: true
  274. content:
  275. application/json:
  276. schema:
  277. $ref: '#/components/schemas/user'
  278. responses:
  279. '201':
  280. description: Created
  281. content:
  282. application/json:
  283. schema:
  284. type: object
  285. properties:
  286. id:
  287. type: string
  288. description: Id of the created user.
  289. links:
  290. get-user:
  291. $ref: '#/components/links/get-user'
  292. update-user:
  293. $ref: '#/components/links/update-user'
  294. delete-user:
  295. $ref: '#/components/links/delete-user'
  296. '/users/{user-id}':
  297. parameters:
  298. - in: path
  299. name: user-id
  300. required: true
  301. schema:
  302. type: integer
  303. format: int64
  304. get:
  305. operationId: get-user
  306. summary: Gets a user by ID
  307. responses:
  308. '200':
  309. description: OK
  310. content:
  311. application/json:
  312. schema:
  313. $ref: '#/components/schemas/user'
  314. '404':
  315. $ref: '#/components/responses/user-not-found'
  316. patch:
  317. operationId: update-user
  318. summary: Updates a user
  319. requestBody:
  320. required: true
  321. content:
  322. application/json:
  323. schema:
  324. $ref: '#/components/schemas/user'
  325. security:
  326. - {}
  327. - userAuth: []
  328. responses:
  329. '200':
  330. description: OK
  331. content:
  332. application/json:
  333. schema:
  334. type: array
  335. items:
  336. $ref: '#/components/schemas/user'
  337. delete:
  338. operationId: delete-user
  339. summary: Deletes a user
  340. responses:
  341. '200':
  342. description: OK
  343. '404':
  344. $ref: '#/components/responses/user-not-found'
  345. security:
  346. - userAuth: []
  347. components:
  348. securitySchemes:
  349. participantAuth:
  350. type: http
  351. scheme: bearer
  352. pollAuth:
  353. type: http
  354. scheme: bearer
  355. resultAuth:
  356. type: http
  357. scheme: bearer
  358. userAuth:
  359. type: http
  360. scheme: bearer
  361. schemas:
  362. ballot:
  363. type: object
  364. properties:
  365. id:
  366. type: integer
  367. description: A unique identifier
  368. example: 4
  369. readOnly: true
  370. mention:
  371. type: integer
  372. description: >-
  373. The mention item, according to the mentions array defined when
  374. creating the poll.
  375. example: 2
  376. proposal:
  377. type: object
  378. properties:
  379. id:
  380. type: integer
  381. description: A unique identifier.
  382. readOnly: true
  383. example: 4
  384. name:
  385. type: string
  386. description: Unique but short name of the proposal.
  387. example: A new school
  388. ballots:
  389. type: array
  390. description: The ballots received by this proposal.
  391. items:
  392. $ref: '#/components/schemas/ballot'
  393. description:
  394. type: string
  395. description: An optional description of the proposal
  396. example: This school would welcome 500 pupils.
  397. required:
  398. - name
  399. mention:
  400. type: object
  401. properties:
  402. id:
  403. type: integer
  404. description: A unique identifier
  405. example: 0
  406. readOnly: true
  407. name:
  408. type: string
  409. description: >-
  410. Unique but short name of the mention, like *Excellent* or *To
  411. reject*.
  412. example: Excellent
  413. description:
  414. type: string
  415. description: An optional description of the mention
  416. example: 'In this poll, the mention *To reject* disqualifies the proposal.'
  417. required:
  418. - name
  419. participant:
  420. type: object
  421. properties:
  422. id:
  423. type: string
  424. description: A unique identifier.
  425. example: JtRm05yjMAuFCI2uwnFp
  426. readOnly: true
  427. description:
  428. type: string
  429. description: An optional description of the participant.
  430. example: John Doe
  431. has-participed:
  432. type: boolean
  433. description: >-
  434. True if the participant already participed to the poll, False
  435. otherwise.
  436. example: true
  437. poll-id:
  438. type: string
  439. description: The identifier of the poll that the participant participates on.
  440. example: 1jDe1e5eF_IkaYPuoIYX
  441. user-id:
  442. type: string
  443. description: The identifier of the user.
  444. example: 1jDe1e5eF_IkaYPuoIYX
  445. mail:
  446. type: string
  447. description: >-
  448. The mail that will eventually created at the creation of the
  449. participant (not kept in memory).
  450. example: john-doe@example.com
  451. required:
  452. - poll-id
  453. poll:
  454. type: object
  455. properties:
  456. id:
  457. type: string
  458. description: A unique identifier
  459. example: 1jDe1e5eF_IkaYPuoIYX
  460. readOnly: true
  461. title:
  462. type: string
  463. example: What project should our neighbourhood invest in for the next year?
  464. description: The title of the poll
  465. description:
  466. type: string
  467. description: A description of the poll
  468. example: null
  469. proposals:
  470. type: array
  471. description: The proposals being voted in a poll.
  472. minItems: 2
  473. maxItems: 20
  474. items:
  475. $ref: '#/components/schemas/proposal'
  476. mentions:
  477. type: array
  478. description: The mentions on which one participant vote to a proposal.
  479. minItems: 2
  480. maxItems: 10
  481. items:
  482. $ref: '#/components/schemas/mention'
  483. participants:
  484. type: array
  485. description: The participants that are allowed to participate to the election.
  486. items:
  487. $ref: '#/components/schemas/participant'
  488. user-id:
  489. type: string
  490. description: 'Organizer id. If not given, a dummy user is created.'
  491. restrict-participants:
  492. type: boolean
  493. description: 'True if anyone can participate to this poll, False otherwise.'
  494. example: false
  495. required:
  496. - title
  497. - proposals
  498. error:
  499. type: object
  500. properties:
  501. code:
  502. type: string
  503. description: The HTTP code of the response
  504. example: 404
  505. message:
  506. type: string
  507. description: The response details
  508. example: The specified participant was not found
  509. required:
  510. - code
  511. - message
  512. result:
  513. type: object
  514. properties:
  515. poll:
  516. $ref: '#/components/schemas/poll'
  517. ranking:
  518. type: array
  519. description: >-
  520. An array representing mentions level for each proposal, according to
  521. the mentions list, following the order of the proposals array
  522. defined when the related poll has been created.
  523. example:
  524. - 0
  525. - 6
  526. - 3
  527. - 2
  528. - 2
  529. minItems: 2
  530. maxItems: 20
  531. items:
  532. type: integer
  533. format: int16
  534. required:
  535. - ranking
  536. - poll
  537. user:
  538. type: object
  539. properties:
  540. id:
  541. type: integer
  542. description: A unique identifier
  543. example: 0
  544. readOnly: true
  545. name:
  546. type: string
  547. description: Unique user-name
  548. example: john.doe
  549. description:
  550. type: string
  551. description: An optional description of the user
  552. example: >-
  553. John Doe is a multiple-use name that is used when the true name of a
  554. person is unknown or is being intentionally concealed
  555. links:
  556. get-poll:
  557. operationId: get-poll
  558. parameters:
  559. pollId: $response.body#/id
  560. description: >
  561. The `id` value returned in the response can be used as the `poll-id`
  562. parameter in GET /polls/{poll-id}.
  563. update-poll:
  564. operationId: update-poll
  565. parameters:
  566. pollId: $response.body#/id
  567. description: >
  568. The `id` value returned in the response can be used as the `poll-id`
  569. parameter in PATCH /polls/{poll-id}.
  570. delete-poll:
  571. operationId: delete-poll
  572. parameters:
  573. pollId: $response.body#/id
  574. description: >
  575. The `id` value returned in the response can be used as the `poll-id`
  576. parameter in DELETE /polls/{poll-id}.
  577. create-ballot:
  578. operationId: create-ballot
  579. parameters:
  580. userId: $response.body#/id
  581. description: >
  582. The `id` value returned in the response can be used as the `poll-id`
  583. parameter in POST /polls/{poll-id}/ballots.
  584. list-poll-results:
  585. operationId: list-poll-results
  586. parameters:
  587. pollId: $response.body#/id
  588. description: >
  589. The `id` value returned in the response can be used as the `poll-id`
  590. parameter in GET /polls/{poll-id}/results.
  591. get-ballot:
  592. operationId: get-ballot
  593. parameters:
  594. ballotId: $response.body#/id
  595. description: >
  596. The `id` value returned in the response can be used as the `ballot-id`
  597. parameter in GET /polls/{poll-id}/ballots/{ballot-id}.
  598. delete-ballot:
  599. operationId: delete-ballot
  600. parameters:
  601. ballotId: $response.body#/id
  602. description: >
  603. The `id` value returned in the response can be used as the `ballot-id`
  604. parameter in DELETE /polls/{poll-id}/ballots/{ballot-id}.
  605. get-user:
  606. operationId: get-user
  607. parameters:
  608. userId: $response.body#/id
  609. description: >
  610. The `id` value returned in the response can be used as the `user-id`
  611. parameter in GET /users/{user-id}.
  612. update-user:
  613. operationId: update-user
  614. parameters:
  615. userId: $response.body#/id
  616. description: >
  617. The `id` value returned in the response can be used as the `user-id`
  618. parameter in PATCH /users/{user-id}.
  619. delete-user:
  620. operationId: delete-user
  621. parameters:
  622. userId: $response.body#/id
  623. description: >
  624. The `id` value returned in the response can be used as the `user-id`
  625. parameter in DELETE /users/{user-id}.
  626. responses:
  627. poll-not-found:
  628. description: The specified poll was not found
  629. content:
  630. application/json:
  631. schema:
  632. $ref: '#/components/schemas/error'
  633. ballot-not-found:
  634. description: The specified ballot was not found
  635. content:
  636. application/json:
  637. schema:
  638. $ref: '#/components/schemas/error'
  639. participant-not-found:
  640. description: The specified participant was not found
  641. content:
  642. application/json:
  643. schema:
  644. $ref: '#/components/schemas/error'
  645. user-not-found:
  646. description: The specified user was not found
  647. content:
  648. application/json:
  649. schema:
  650. $ref: '#/components/schemas/error'