diff --git a/mvapi.yaml b/mvapi.yaml new file mode 100644 index 0000000..70861ed --- /dev/null +++ b/mvapi.yaml @@ -0,0 +1,361 @@ +openapi: 3.0.0 +info: + title: Mieux Voter + description: >- + An Application Programming Interface (API) for Majority Judgment (MJ) + Polling. + version: "1.0.1-oas3" + termsOfService: 'https://github.com/MieuxVoter' + contact: + email: app@mieuxvoter.fr +servers: + - url: 'https://api.mieuxvoter.fr/v1' + description: 'Main (production) server' + - url: 'https://sandboxapi.mieuxvoter.fr/v1' + description: 'Internal staging server for testing' +paths: + /polls: + get: + summary: Gets all polls. + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Poll' + post: + summary: Creates a poll. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Poll' + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: Id of the created poll. + links: + GetPollByPollId: + $ref: '#/components/links/GetPollByPollId' + SetPollByPollId: + $ref: '#/components/links/SetPollByPollId' + DelPollByPollId: + $ref: '#/components/links/DelPollByPollId' + JudgeByPollId: + $ref: '#/components/links/JudgeByPollId' + ResultsByPollId: + $ref: '#/components/links/ResultsByPollId' + '400': + description: Bad Request. Expect at least 2 candidates and a title. + '/polls/{pollId}': + parameters: + - in: path + name: pollId + required: true + schema: + type: integer + format: int64 + get: + summary: Gets a poll by ID + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Poll' + '404': + $ref: '#/components/responses/PollNotFound' + patch: + summary: Updates a poll + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Poll' + security: + - {} + - pollAuth: [] + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Poll' + delete: + summary: Deletes a poll + responses: + '200': + description: OK + '404': + $ref: '#/components/responses/PollNotFound' + security: + - {} + - pollAuth: [] + '/judgments/{pollId}': + parameters: + - in: path + name: pollId + required: true + schema: + type: string + post: + summary: Creates a judgment + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Judgment' + security: + - {} + - judgeAuth: [] + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: Id of the created judgment. + links: + GetJudgmentByJudgmentId: + $ref: '#/components/links/GetJudgmentByJudgmentId' + DelJudgmentByJudgmentId: + $ref: '#/components/links/DelJudgmentByJudgmentId' + '/judgments/{judgmentId}': + parameters: + - in: path + name: judgmentId + required: true + schema: + type: string + get: + summary: Gets a judgment by ID + responses: + '200': + description: A judgment object + content: + application/json: + schema: + $ref: '#/components/schemas/Judgment' + delete: + summary: Deletes a judgment + responses: + '200': + description: OK + '404': + description: Judgment not found + security: + - {} + - judgeAuth: [] + '/invites/{pollId}': + parameters: + - in: path + name: pollId + required: true + schema: + type: string + post: + description: Invite a judge to a poll + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Invite' + responses: + '200': + description: Invitation was sent + content: + text/plain: + schema: + type: string + '404': + $ref: '#/components/responses/PollNotFound' + '/results/{pollId}': + parameters: + - in: path + name: pollId + required: true + schema: + type: string + get: + description: Get results of a poll + responses: + '200': + description: OK + content: + text/plain: + schema: + $ref: '#/components/schemas/Result' + '404': + $ref: '#/components/responses/PollNotFound' +components: + responses: + PollNotFound: + description: The specified poll was not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + Unauthorized: + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + schemas: + Grade: + type: object + properties: + id: + type: string + readOnly: true + name: + type: string + description: Unique but short name of the candidate. + Judgment: + type: object + properties: + id: + type: string + readOnly: true + grade: + type: string + Candidate: + type: object + properties: + id: + type: string + readOnly: true + name: + type: string + description: Unique but short name of the candidate. + judgments: + type: array + items: + $ref: '#/components/schemas/Judgment' + description: The judgments received by this candidate. + Poll: + type: object + properties: + id: + type: string + readOnly: true + title: + type: string + description: 'As