開発中にフロントエンドからデータを取るにはどう書けばいいんだっけ？と悩むことはありませんか。
本記事ではサブスク管理人のAPI設計を紹介します。

APIの設計

AIと検討を重ねた結果、次のようなAPI設計となりました。

ユーザーの登録から退会までを管理するエンドポイントです。
メールアドレスとパスワードによる構成を採用しました。パスワードはハッシュ化してDBに保存してます。

メイン機能であるサブスクリプション情報のCRUD操作です。登録と更新時にはバリデーションチェックを行います。

エンドポイント	説明	主なデータ項目
GET /subscriptions	登録済み一覧取得	id, name, price, billing_cycle, next_billing_date
POST /subscriptions	新規登録	name, price, billing_cycle, next_billing_date
PUT /subscriptions/{id}	情報の更新	name, price, billing_cycle, next_billing_date
DELETE /subscriptions/{id}	データの削除	id

利便性を高めるための補助的なエンドポイントです。

エンドポイント	説明	取得データ
GET /presets	プリセット情報取得	name, price, billing_cycle, icon_url
GET /health	死活監視	status

認証、セキュリティ

認証はBearer Authによるトークン認証を採用しています。

セッションはログイン成功時に発行されるアクセストークンをヘッダーに含めることで認証状態を維持する設計としています。

APIの設計はOpenAPI形式で記述しopenapi.yamlファイルで管理しています。
設計をコード化したことで、AIがエンドポイントやデータ構造を正しく理解でき実装提案の質があがり、開発速度が向上しました。

サブスク管理人のAPIリファレンスは、下記ページから閲覧できます。

APIリファレンスページはredoclyを利用することでファイルから自動で生成可能です。

npx @redocly/cli build-docs ./docs/openapi.yaml -o ./docs/index.html

上記コマンドで変換しています。

API設計をファイル化し、AIと開発を進めてスピード感を持って開発できました。簡単なCRUD操作はもう人間が作ることはせず、全体設計やレビューに注力することが重要だと実感しました。