API設計

基本方針

• RESTful(リソース＋操作)でサービスを表現する
  • REpresentational State Transfer
    • 参考：AWS RESTful API とは?
  • 例：GET /users
  • 採用しない方式
    • RPC : Remote Procedure Call
      • POST /getUsers
      • 参考 : RPC と REST の違いはなんですか?
    • BFF : Backend For Frontend
      • GET /dashboard/users
• openapi(FastAPIで自動生成)でドキュメンテーションする
• 参考：翻訳: WebAPI 設計のベストプラクティス

パス設計

• パスはspinal-caseで記述する
  • Google推奨形式
  • パラメータはjs利用前提を考慮する場合、camelCaseで記述する。
• シングルトンかマルチプルかは単数形か複数形かで正しく表現する
  • 特定の一人のユーザ
    • user
  • 複数のユーザ
    • users
• リソースをうまく表現する
  • 例：ユーザ同期リソースのステータスプロパティを表現する
    • × user/sync/status
      • ユーザ(user)が持つ同期(sync)が持つステータス(status)とも取れる
      • ユーザ同期 ≠ ユーザではないことが分かりにくい。
    • 〇 user-sync/status
      • ユーザ同期user-syncが持つステータス(status)を表現するので誤解を与えにくいはず。
• バージョンはメジャーバージョンのみ記載

操作一覧

操作名	コード	HTTPメソッド	説明
Get	0	GET	単一のリソース（シングルトン）を取得する操作。
List	1	GET	全リソースを絞り込まずに一覧する操作。ページングは動作想定。複雑なフィルタ等行う際はQueryにすることを検討する。
Create	2	POST	リソースを新規に作成する操作。
Patch	3	PATCH	既存リソースを部分的に変更する操作。
Upsert	4	PUT	リソース置換操作。既存リソースがなければ作成する操作。
Delete	5	DELETE	リソースを削除する操作。
Query	7	POST	特定の問い合わせ処理を要求する。フィルタ条件を隠蔽化したいときなど。検索結果などをレスポンスに含めること。

設計例

APIアクションコード（RRA）	APIアクション	HTTP Method	URI	操作
0000	GetHealth	GET	/health	ヘルス取得
1000	GetUser	GET	/users/{userId}	ユーザ取得
1002	CreateUser	POST	/users	ユーザ作成
1003	PatchUser	PATCH	/users/{userId}	ユーザ更新
1005	DeleteUser	DELETE	/users/{userId}	ユーザ削除
1007	QueryUser	POST	/query/users	ユーザ検索

複製操作

• Createのエンドポイントに複製元のidを渡すという設計が可能
• Backend Engineerに贈る初めてのREST APIのURI設計 : リソースの新規作成のバリエーション