Vote System API仕様書

1. 概要

Vote - 投票
選挙の参加者が意見を出すこと。
ユーザーの投票データの管理および投票の現状・結果を取得する機能の集まり。
本サービスでは参加者が選択したものを指すとき「候補」という表現を使用せず、「アイテム(item)」という表現を使用する。正規表現により入力可能な値の数が無限になる場合があるためである。

2. 投票を記録する。

2.1. Request

POST /elections/cd0334ba-239a-42df-bc12-b2213a938ffc/votes HTTP/1.1
Content-Type: application/json
Content-Length: 46
Host: localhost:8080

{
  "userId" : "user-01",
  "item" : "12-34"
}

Path Parameter ./elections/{electionId}/votes

Parameter Description

Parameter	Description
`electionId`	選挙識別子

electionId

選挙識別子

Request Fields

Path Type Description

Path	Type	Description
`userId`	`String`	投票をするユーザーのＩＤ
`item`	`String`	ユーザーが投票したアイテム

userId

String

投票をするユーザーのＩＤ

item

String

ユーザーが投票したアイテム

2.2. Response

2.2.1. 201 Created

HTTP/1.1 201 Created
Location: /elections/cd0334ba-239a-42df-bc12-b2213a938ffc/votes/user-01
Content-Type: application/json
Content-Length: 150

{
  "electionId" : "cd0334ba-239a-42df-bc12-b2213a938ffc",
  "userId" : "user-01",
  "item" : "12-34",
  "votedAt" : "2026-02-22T12:27:03.746476598"
}

Response Fields

Path Type Description

Path	Type	Description
`electionId`	`String`	選挙識別子
`userId`	`String`	投票をするユーザーのＩＤ
`item`	`String`	ユーザーが投票したアイテム
`votedAt`	`String`	投票時間

electionId

String

選挙識別子

userId

String

投票をするユーザーのＩＤ

item

String

ユーザーが投票したアイテム

votedAt

String

投票時間

2.2.2. 404 NOT FOUND [指定したＩＤの選挙が存在しない場合]

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 150

{
  "state" : "404 NOT_FOUND",
  "message" : "Election Not Found.",
  "errorCode" : "ELECTION_001",
  "detail" : "voteId wrongElectionId not found."
}

2.2.3. 400 BAD REQUEST [有効ではないitem]

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 133

{
  "state" : "400 BAD_REQUEST",
  "message" : "Invalid Item",
  "errorCode" : "VOTE_003",
  "detail" : "item 12-asd is not valid."
}

2.2.4. 400 BAD REQUEST [有効ではないitemユーザーのＩＤ]

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 140

{
  "state" : "400 BAD_REQUEST",
  "message" : "Invalid UserId",
  "errorCode" : "VOTE_004",
  "detail" : "userId tester-01 is not valid."
}

3. 投票の記録を取得する。

3.1. Request

GET /elections/0afa7f60-2ecf-426f-a8ce-c8dbe0d5d0c5/votes/user-01 HTTP/1.1
Host: localhost:8080

Path Parameter ./elections/{electionId}/votes/{userId}

Parameter Description

Parameter	Description
`electionId`	選挙識別子
`userId`	ユーザーのＩＤ

electionId

選挙識別子

userId

ユーザーのＩＤ

3.2. Response

3.2.1. 200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 140

{
  "electionId" : "0afa7f60-2ecf-426f-a8ce-c8dbe0d5d0c5",
  "userId" : "user-01",
  "item" : "12-34",
  "votedAt" : "2026-02-22T12:27:04"
}

Response Fields

Path Type Description

Path	Type	Description
`electionId`	`String`	選挙識別子
`userId`	`String`	投票をするユーザーのＩＤ
`item`	`String`	ユーザーが投票したアイテム
`votedAt`	`String`	投票時間

electionId

String

選挙識別子

userId

String

投票をするユーザーのＩＤ

item

String

ユーザーが投票したアイテム

votedAt

String

投票時間

3.2.2. 404 NOT FOUND [指定したＩＤの選挙が存在しない場合]

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 163

{
  "state" : "404 NOT_FOUND",
  "message" : "Vote Not Found.",
  "errorCode" : "VOTE_002",
  "detail" : "voteId 48bfe756-81d5-4641-8f70-469fce8667e7 not found."
}

3.2.3. 404 NOT FOUND [指定したＩＤのユーザーの投票記録が存在しない場合]

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 163

{
  "state" : "404 NOT_FOUND",
  "message" : "Vote Not Found.",
  "errorCode" : "VOTE_002",
  "detail" : "voteId 6f9ef295-e33b-42d3-bb2d-44527c4b6462 not found."
}

4. itemごとの獲得投票数を取得する

4.1. Request

GET /elections/b0baa51b-fafc-494a-a013-1617ebd7b6b9/votes/statistic HTTP/1.1
Host: localhost:8080

Path Parameter ./elections/{electionId}/votes/statistic

Parameter Description

Parameter	Description
`electionId`	選挙識別子

electionId

選挙識別子

4.2. Response

4.2.1. 200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 418

{
  "voteCounts" : [ {
    "item" : "00-02",
    "voteCount" : 4
  }, {
    "item" : "02-01",
    "voteCount" : 4
  }, {
    "item" : "00-01",
    "voteCount" : 3
  }, {
    "item" : "01-02",
    "voteCount" : 3
  }, {
    "item" : "02-00",
    "voteCount" : 3
  }, {
    "item" : "00-00",
    "voteCount" : 2
  }, {
    "item" : "02-02",
    "voteCount" : 1
  } ],
  "aggregatedAt" : "2026-02-22T12:27:03.592394969"
}

Response Fields

Path Type Description

Path	Type	Description
`aggregatedAt`	`String`	選択時間
`voteCounts.[].item`	`String`	投票をもらったアイテム
`voteCounts.[].voteCount`	`Number`	アイテムの投票をもらった数

aggregatedAt

String

選択時間

voteCounts.[].item

String

投票をもらったアイテム

voteCounts.[].voteCount

Number

アイテムの投票をもらった数

4.2.2. 404 NOT FOUND [指定したＩＤの選挙が存在しない場合]

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 171

{
  "state" : "404 NOT_FOUND",
  "message" : "Election Not Found.",
  "errorCode" : "ELECTION_001",
  "detail" : "voteId b82d56b6-8f7f-4f67-9638-dec5ddfc8ce1 not found."
}

5. ユーザーの投票をキャンセルする

5.1. Request

DELETE /elections/07783a65-1f23-45d8-8106-60eb586aae8b/votes/user-01 HTTP/1.1
Host: localhost:8080

Path Parameter ./elections/{electionId}/votes/{userId}

Parameter Description

Parameter	Description
`electionId`	選挙識別子
`userId`	ユーザーのＩＤ

electionId

選挙識別子

userId

ユーザーのＩＤ

5.2. Response

5.2.1. 200 OK

HTTP/1.1 200 OK

5.2.2. 404 NOT FOUND [指定したＩＤの選挙が存在しない場合]

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 188

{
  "state" : "404 NOT_FOUND",
  "message" : "Vote Not Found.",
  "errorCode" : "VOTE_002",
  "detail" : "electionId: 69b9f5c9-2c8e-471a-9b2d-5dcdb40e8000, userId: user-01 is not found."
}

5.2.3. 404 CONFLICT [選挙が進行中でばない場合]

HTTP/1.1 409 Conflict
Content-Type: application/json
Content-Length: 170

{
  "state" : "409 CONFLICT",
  "message" : "Election Is Not Open.",
  "errorCode" : "VOTE_001",
  "detail" : "voteId a19573f9-f70a-46a4-8ca4-235fea60055b is not open."
}

6. 投票記録のitemを変更

すでに投票したユーザーが他のものを選択した時の処理。
選択したitemを変更された場合、votedAt も更新される。

6.1. Path Parameter

Table 1. /elections/{electionId}/votes/{userId}
Parameter	Description
`electionId`	投票識別子
`userId`	ユーザーのＩＤ

6.2. Request

PATCH /elections/1752306e-237f-4d4b-8878-963cdc5899d6/votes/user-01 HTTP/1.1
Content-Type: application/json
Content-Length: 22
Host: localhost:8080

{
  "item" : "99-99"
}

Request Fields

Path Type Description

Path	Type	Description
`item`	`String`	変更するアイテム

item

String

変更するアイテム

6.3. Response

6.3.1. 200 OK

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 149

{
  "electionId" : "1752306e-237f-4d4b-8878-963cdc5899d6",
  "userId" : "user-01",
  "item" : "99-99",
  "votedAt" : "2026-02-22T12:27:03.33787981"
}

Response Fields

Path Type Description

Path	Type	Description
`electionId`	`String`	選挙識別子
`userId`	`String`	投票をするユーザーのＩＤ
`item`	`String`	ユーザーが投票したアイテム
`votedAt`	`String`	投票時間

electionId

String

選挙識別子

userId

String

投票をするユーザーのＩＤ

item

String

ユーザーが投票したアイテム

votedAt

String

投票時間

6.3.2. 409 CONFLICT [選挙が進行中でばない場合]

HTTP/1.1 409 Conflict
Content-Type: application/json
Content-Length: 170

{
  "state" : "409 CONFLICT",
  "message" : "Election Is Not Open.",
  "errorCode" : "VOTE_001",
  "detail" : "voteId 5ad91c5d-73a8-498b-a417-95b83ec30f50 is not open."
}

6.3.3. 404 NOT FOUND [指定したＩＤの選挙が存在しない場合]

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 171

{
  "state" : "404 NOT_FOUND",
  "message" : "Election Not Found.",
  "errorCode" : "ELECTION_001",
  "detail" : "voteId 2c478e93-0147-436a-83fb-85130b0c48c5 not found."
}

6.3.4. 400 BAD REQUEST [有効ではないuserId]

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 146

{
  "state" : "400 BAD_REQUEST",
  "message" : "Invalid UserId",
  "errorCode" : "VOTE_004",
  "detail" : "userId sung-the-tester is not valid."
}

6.3.5. 400 BAD REQUEST [有効ではないitem]

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 133

{
  "state" : "400 BAD_REQUEST",
  "message" : "Invalid Item",
  "errorCode" : "VOTE_003",
  "detail" : "item 132-32 is not valid."
}

Vote System API仕様書 - Vote