概要

自分用の家計簿アプリケーション。

出費を1件ずつ登録していき、月ごとに出費の一覧や合計金額を確認できるようにする。費目ごとの絞り込みにも対応する。

Front-End

React（Next.js）でフロントエンドを作成する予定

詳細は、Issue #2 フロントエンドの作成 に記載

Server-Side

REST API

家計簿に対して登録済みの出費を検索したり、出費の登録/更新/削除を行ったりするためのREST APIを提供する

概要	メソッド	URL
出費の一覧を取得	GET	/api/expenseBook/list/{yyyyMM}
出費の詳細を取得	GET	/api/expenseBook/detail/{id}
出費の追加	POST	/api/expenseBook
出費の更新	PUT	/api/expenseBook/{id}
出費の削除	DELETE	/api/expenseBook/{id}

認証について

このREST APIでは、Json Web Token（JWT）による認証および認可を行っている。

リクエストを送る際、ヘッダーのAuthorizationフィールドに、Bearer {token}の形式でJWTを送信する。 JWTの発行機能はまだないため、開発者より個別に取得すること。

JWTの構成要素

この家計簿アプリで使用するJWTは下記の構成になっていることを想定している

ヘッダー

• typ
  • トークンの種類。ここではJWT
• alg
  • アルゴリズム。ここではRS256

{
  "alg": "RS256",
  "typ": "JWT"
}

ペイロード

• sub
  • 家計簿にアクセスしているユーザーのID
• issuer
  • トークンの発行元
• scope
  • トークンに付与された権限範囲。家計簿アプリで扱う権限は下記の2種類
  • 1つのトークンが2種類両方の権限を持つことも可能
  • expense:read: 家計を閲覧する権限
  • expense:write: 家計を編集（登録、更新、削除）する権限
• iat
  • トークンの発行日時。UNIXタイムスタンプ形式
• exp
  • トークンの有効期限。UNIXタイムスタンプ形式

{
  "sub": "1",
  "issuer": "http://localhost:8080",
  "scope": [
    "expense:read",
    "expense:write"
  ],
  "iat": 1725425558,
  "exp": 1735657199
}

署名

ヘッダーとペイロードを繋げた文字列を、秘密鍵を用いて署名した値

出費の一覧を取得

• 概要: 家計簿に登録済みされている特定の年月の出費一覧を取得する。費目での絞り込みも可能
• URL: /api/expenseBook/list/{yyyyMM}
• メソッド: GET
• 認可: 閲覧用のトークンが必要

パスパラメータ

name	required	value
yyyyMM	◯	取得する出費の年月。yyyyMM形式

クエリパラメータ

name	required	value
types		絞り込む費目をコードで指定する。複数指定可能。指定されなければ全て取得する。コードの詳細は「その他補足事項」参照

レスポンス

• 200 OK: 出費のリストを返します

レスポンスボディ

Content-Type: application/json

[
  {
    "id": "5bcfeb53-6961-475a-b10a-8bbd644993d9",
    "date": "2024-07-12",
    "price": 1800,
    "store": "スーパーマーケット",
    "usage": "食料品",
    "type": 1
  },
  {
    "id": "2e24a6b2-0f57-469b-9a9b-d02755c8f217",
    "date": "2024-07-13",
    "price": 5000,
    "store": "レストラン",
    "usage": "夕食",
    "type": 2
  }
]

出費の詳細を取得

• URL: /api/expenseBook/detail/{id}
• メソッド: GET
• 概要: 家計簿に登録済みされている出費の詳細を取得する
• 認可: 閲覧用のトークンが必要

パスパラメータ

name	required	value
id	◯	取得する出費のid

レスポンス

• 200 OK: 出費の詳細を返します

Content-Type: application/json

{
  "id": "5bcfeb53-6961-475a-b10a-8bbd644993d9",
  "date": "2024-07-12",
  "price": 1800,
  "store": "スーパーマーケット",
  "usage": "食料品",
  "type": 1
}

• 404 Not Found: 指定された出費が存在しませんでした

出費の追加

• URL: /api/expenseBook
• メソッド: POST
• 概要: 出費1件を家計簿に登録する
• 認可: 編集用のトークンが必要

リクエスト

リクエストボディ

Content-Type: application/json

name	required	value
date	◯	出費の日付
price	◯	出費金額。マイナスも可
store		支払先
usage		使途
type	◯	費目のコード。詳細は「その他補足事項」参照

e.g.

{
  "date": "2024-07-12",
  "price": 1000,
  "store": "スーパーマーケット",
  "usage": "食料品",
  "type": 1
}

レスポンス

• 201 Created: 出費が正常に登録されました

Content-Type: application/json

{
  "id": "5bcfeb53-6961-475a-b10a-8bbd644993d9",
  "date": "2024-07-12",
  "price": 1000,
  "store": "スーパーマーケット",
  "usage": "食料品",
  "type": 1
}

出費の更新

• URL: /api/expenseBook/{id}
• メソッド: PUT
• 概要: 家計簿に登録済みの出費1件を更新する
• 認可: 編集用のトークンが必要

リクエスト

パスパラメータ

name	required	value
id	◯	更新する出費のid

リクエストボディ

Content-Type: application/json

name	required	value
date	◯	出費の日付
price	◯	出費金額。マイナスも可
store		支払先
usage		使途
type	◯	費目のコード。コードの詳細は「その他補足事項」参照

e.g.

{
  "id": "5bcfeb53-6961-475a-b10a-8bbd644993d9",
  "date": "2024-07-12",
  "price": 1800,
  "store": "スーパーマーケット",
  "usage": "食料品",
  "type": 1
}

レスポンス

• 204 No Content: 更新が正常に反映されました

Content-Type: application/json

{
  "id": "5bcfeb53-6961-475a-b10a-8bbd644993d9",
  "date": "2024-07-12",
  "price": 1800,
  "store": "スーパーマーケット",
  "usage": "食料品",
  "type": 1
}

• 404 Not Found: 指定された出費が存在しませんでした

出費の削除

• URL: /api/expenseBook/{id}
• メソッド: DELETE
• 概要: 家計簿に登録済みの出費1件を削除する
• 認可: 編集用のトークンが必要

リクエスト

パスパラメータ

name	required	value
id	◯	更新する出費のid

レスポンス

• 204 No Content: 削除が正常に実行されました

• 404 Not Found: 指定された出費が存在しませんでした

その他補足事項

費目コード

リクエストで指定できる費目のコード一覧

コード	費目
1	食費・雑費（スーパーなど）
2	食費・雑費（外食など）
3	娯楽
4	身だしなみ
5	ガソリン
6	設備
7	学習
8	医療
9	その他

DB

出費履歴

name	type	PK	not null	default	description
id	uuid	◯	◯	gen_random_uuid()	出費を一意にするid
支払日	date		◯		支払った日付
費目cd	integer		◯		費目マスターの費目cd
金額	integer		◯		支払った金額。マイナスも許容する
支払先	text		◯		支払先
使途	text		◯		購入した物品や受けたサービス内容
最終更新者id	integer		◯		出費を最後に更新したユーザー
最終更新日時	timestamp		◯	CURRENT_TIMESTAMP	出費を最後に更新した日時

費目マスター

name	type	PK	not null	default	description
費目cd	integer	◯	◯		費目を一意にするコード
費目名	text		◯		費目の名称
有効区分	boolean		◯	true	費目の有効区分。無効の場合、新規登録で選択できなくなる