1. 概要

Election - 選挙
選挙を初めて人の投票をもらって結果を出すまでの一連のプロセスを意味する。
選挙の識別子、状態、開始時間などの選挙に関するデータをあつかる機能の集まり。

2. 投票生成

2.1. Request

POST /elections HTTP/1.1
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded

2.2. Response

2.2.1. 200 OK

HTTP/1.1 201 Created
Location: /elections/bd5fcbe0-99a2-4839-ace4-62ff0e772120
Content-Type: application/json
Content-Length: 62

{
  "newElectionId" : "bd5fcbe0-99a2-4839-ace4-62ff0e772120"
}

Response Fields

Path Type Description

newElectionId

String

生成された選挙のＩＤ

idは選挙が生成されるとき、バックエンド側で生成される。
選挙を制御するとき特定するため必要。

3. 全ての選挙を取得する。

3.1. Request

GET /elections HTTP/1.1
Host: localhost:8080

3.2. Response

3.2.1. 200 OK

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

[ {
  "id" : "1327b9b7-4391-41f5-a508-30dfea8700ee",
  "state" : "open",
  "startedAt" : "2026-02-22T12:27:02",
  "endedAt" : null,
  "createdAt" : "2026-02-22T12:27:02"
}, {
  "id" : "ee89c78b-f853-43a6-afeb-1e39732b4fd6",
  "state" : "close",
  "startedAt" : null,
  "endedAt" : null,
  "createdAt" : "2026-02-22T12:27:02"
}, {
  "id" : "39056649-c259-4ccf-b74c-efd503d24ba4",
  "state" : "close",
  "startedAt" : null,
  "endedAt" : null,
  "createdAt" : "2026-02-22T12:27:02"
}, {
  "id" : "38e1cda1-ddd0-430b-9dfb-cd63ce72a60b",
  "state" : "close",
  "startedAt" : null,
  "endedAt" : null,
  "createdAt" : "2026-02-22T12:27:02"
}, {
  "id" : "59fa00df-2382-4498-a737-20dd1099b736",
  "state" : "close",
  "startedAt" : "2026-02-22T12:27:02",
  "endedAt" : "2026-02-22T12:27:02",
  "createdAt" : "2026-02-22T12:27:02"
}, {
  "id" : "953bb7d2-95ca-46ee-b6b8-486aec1cff3c",
  "state" : "close",
  "startedAt" : "2026-02-22T12:27:02",
  "endedAt" : "2026-02-22T12:27:02",
  "createdAt" : "2026-02-22T12:27:02"
} ]

Response Fields

Path Type Description

[].id

String

選挙識別子

[].state

String

進行の有無

[].startedAt

String

開始時間

[].endedAt

String

終了時間

[].createdAt

String

生成時間

注意 データベースに大量の選挙データが保存されている場合、性能上の問題が発生する可能性があります。

4. ページングを用いて一部のデータを取得する。

4.1. Request

GET /elections?page=2&size=3 HTTP/1.1
Host: localhost:8080

Query Parameters

Parameter Description

page

ページ

size

一つのページに含めるデータの数

4.2. Response

4.2.1. 200 OK

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

[ {
  "id" : "9fc20927-9f5c-4fc5-8ce3-cfaa0f6644ee",
  "state" : "close",
  "startedAt" : null,
  "endedAt" : null,
  "createdAt" : "2026-02-22T12:27:01"
}, {
  "id" : "a629b16e-4f42-41d8-af63-2f022f463c1a",
  "state" : "close",
  "startedAt" : null,
  "endedAt" : null,
  "createdAt" : "2026-02-22T12:27:01"
}, {
  "id" : "a5338109-9244-4f16-ac3c-63a160997ede",
  "state" : "open",
  "startedAt" : "2026-02-22T12:27:01",
  "endedAt" : null,
  "createdAt" : "2026-02-22T12:27:01"
} ]

4.2.2. Response Fields

Path Type Description

[].id

String

選挙の識別子

[].state

String

進行の有無

[].startedAt

String

開始時間

[].endedAt

Null

終了時間

[].createdAt

String

生成時間

4.2.3. 400 BAD REQUEST [page に 1 未満の値を指定した場合]

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

{
  "state" : "400 BAD_REQUEST",
  "message" : "Invalid Paging Parameters",
  "errorCode" : "PAGING_ERROR",
  "detail" : "page 값이 잘못 되었습니다."
}

4.2.4. 400 BAD REQUEST [size に 1 未満の値を指定した場合]

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

{
  "state" : "400 BAD_REQUEST",
  "message" : "Invalid Paging Parameters",
  "errorCode" : "PAGING_ERROR",
  "detail" : "size는 1이상이어야 합니다."
}

5. idで一つの選挙を取得する

5.1. Request

GET /elections/ee1fcad6-af20-4e08-988d-f381f11393d9 HTTP/1.1
Host: localhost:8080

Path Parameters ./elections/{electionId}

Parameter Description

electionId

選挙識別子

5.2. Response

5.2.1. 200 OK

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

{
  "id" : "ee1fcad6-af20-4e08-988d-f381f11393d9",
  "state" : "close",
  "startedAt" : null,
  "endedAt" : null,
  "createdAt" : "2026-02-22T12:27:02"
}

5.2.2. Response Fields

Path Type Description

id

String

選挙の識別子

state

String

進行の有無

startedAt

Null

開始時間

endedAt

Null

終了時間

createdAt

String

生成時間

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

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

{
  "state" : "404 NOT_FOUND",
  "message" : "Election Not Found.",
  "errorCode" : "ELECTION_001",
  "detail" : "electionId: uuid-not-exists"
}

6. 選挙を削除する

6.1. Request

DELETE /elections/950d3e9e-3bdf-4173-a8cc-3052334cf20f HTTP/1.1
Host: localhost:8080

Path Parameters ./elections/{electionId}

Parameter Description

electionId

投票識別子

6.2. Response

6.2.1. 200 OK

HTTP/1.1 200 OK

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

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

{
  "state" : "404 NOT_FOUND",
  "message" : "Election Not Found.",
  "errorCode" : "ELECTION_001",
  "detail" : "electionId: b31324ce-39af-43e7-9307-0f5c3d06ee46"
}

7. 投票を開始する。

7.1. Request [選挙を開始(open)する]

PATCH /elections/d688d545-e279-4ab1-bfdd-aaee4d4304be/state HTTP/1.1
Content-Type: application/json
Content-Length: 25
Host: localhost:8080

{
  "newState" : "open"
}

Path Parameters ./elections/{electionId}/state

Parameter Description

electionId

選挙識別子

Request Fields

Path Type Description

newState

String

変更する状態

7.2. Response

7.2.1. 200 OK

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

{
  "electionId" : "d688d545-e279-4ab1-bfdd-aaee4d4304be",
  "newState" : "open",
  "updatedTime" : "2026-02-22T12:27:00.283786886"
}

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

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

{
  "state" : "404 NOT_FOUND",
  "message" : "Election Not Found.",
  "errorCode" : "ELECTION_001",
  "detail" : "electionId: 9142dfd2-21db-4b53-b495-96f310163133"
}

7.2.3. 400 BAD REQUEST [有効ではない状態に変更しようとした場合]

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

{
  "state" : "400 BAD_REQUEST",
  "message" : "Validation Failed",
  "errorCode" : "VALID_ERROR",
  "detail" : "Validation failed for argument [1] in public java.lang.Object com.yareach.voting_system.election.controller.ElectionController.changeElectionState(java.lang.String,com.yareach.voting_system.election.dto.ChangeElectionStateRequestDto,kotlin.coroutines.Continuation<? super org.springframework.http.ResponseEntity<com.yareach.voting_system.election.dto.ChangeElectionStateResponseDto>>): [Field error in object 'changeElectionStateRequestDto' on field 'newState': rejected value [wrong state]; codes [Pattern.changeElectionStateRequestDto.newState,Pattern.newState,Pattern.java.lang.String,Pattern]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [changeElectionStateRequestDto.newState,newState]; arguments []; default message [newState],[Ljakarta.validation.constraints.Pattern$Flag;@6a82d4b4,open|close]; default message [state는 open과 close 둘만 가능합니다.]] "
}

8. 投票を終了する。

8.1. Request

PATCH /elections/e3484ceb-a8bf-424d-89aa-5bf190eaa545/state HTTP/1.1
Content-Type: application/json
Content-Length: 26
Host: localhost:8080

{
  "newState" : "close"
}

Path Parameters ./elections/{electionId}/state

Parameter Description

electionId

選挙識別子

Request Fields

Path Type Description

newState

String

変更する状態

8.2. Response

8.2.1. 200 OK

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

{
  "electionId" : "e3484ceb-a8bf-424d-89aa-5bf190eaa545",
  "newState" : "close",
  "updatedTime" : "2026-02-22T12:27:00.404201397"
}

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

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

{
  "state" : "404 NOT_FOUND",
  "message" : "Election Not Found.",
  "errorCode" : "ELECTION_001",
  "detail" : "electionId: 9142dfd2-21db-4b53-b495-96f310163133"
}

8.2.3. 400 BAD REQUEST [有効ではない状態に変更しようとした場合]

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

{
  "state" : "400 BAD_REQUEST",
  "message" : "Validation Failed",
  "errorCode" : "VALID_ERROR",
  "detail" : "Validation failed for argument [1] in public java.lang.Object com.yareach.voting_system.election.controller.ElectionController.changeElectionState(java.lang.String,com.yareach.voting_system.election.dto.ChangeElectionStateRequestDto,kotlin.coroutines.Continuation<? super org.springframework.http.ResponseEntity<com.yareach.voting_system.election.dto.ChangeElectionStateResponseDto>>): [Field error in object 'changeElectionStateRequestDto' on field 'newState': rejected value [wrong state]; codes [Pattern.changeElectionStateRequestDto.newState,Pattern.newState,Pattern.java.lang.String,Pattern]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [changeElectionStateRequestDto.newState,newState]; arguments []; default message [newState],[Ljakarta.validation.constraints.Pattern$Flag;@6a82d4b4,open|close]; default message [state는 open과 close 둘만 가능합니다.]] "
}