Merge pull request #1503 from future-architect/feature

Web API Guidelines

Author: ma91n

source/_posts/20250513b_Web_API設計ガイドラインを公開しました.md

@@ -0,0 +1,61 @@
+---
+title: "Web API設計ガイドラインを公開しました"
+date: 2025/05/13 00:00:01
+postid: b
+tag:
+  - ガイドライン
+  - WebAPI
+  - OpenAPI
+category:
+  - Programming
+thumbnail: /images/20250513b/thumbnail.png
+author: 佐藤尭彰
+lede: "Web API に関するガイドラインも昨年11月から検討を開始し、今年の 1/17 に[公開されました！本記事はその紹介になります。 "
+---
+<img src="/images/20250513b/image.png" alt="" width="1200" height="615" loading="lazy">
+
+こんにちは。Strategic AI Group の佐藤です。
+
+フューチャーでは [さまざまなガイドラインを公開しており](https://future-architect.github.io/arch-guidelines/) 、本ブログでも [「ガイドライン」タグ](/tags/%E3%82%AC%E3%82%A4%E3%83%89%E3%83%A9%E3%82%A4%E3%83%B3/) に過去の紹介記事がいくつか載っています。Web API に関するガイドラインも昨年11月から検討を開始し、今年の 1/17 に [公開されました！](https://future-architect.github.io/arch-guidelines/documents/forWebAPI/web_api_guidelines.html)
+
+本記事はそのご紹介です。 ~~4ヶ月も寝かせていて本当に申し訳ありません~~
+
+# 本ガイドラインの経緯
+
+フューチャーでは様々な規模、様々な環境で動くシステムを構築しています。システム開発におけるバックエンド設計かくあるべしという共通知識は大規模システムに偏っていて、昨今急速に数を増やしている Web ベースのシステムに限った話というものはあまり言語化されていませんでした。
+
+そこで今回、設計の属人性を軽減させ、知識の横展開を容易にするべくガイドラインを作成・公開しました。当初はHTTPメソッドやステータスコードの使い分け、認証等々引っかかりやすい部分を具体化する想定でしたが、あれやこれやと増えていき、最終的にはかなりの分量になったと思います。
+
+<img src="/images/20250513b/image_2.png" alt="" width="1200" height="351" loading="lazy">
+
+勿論これらすべてがフューチャーの全プロジェクト、全チームでそのまま適用されているわけではありません。あくまで有志が持ち寄った解のうちでもっとも社内一般に妥当するものを選び、将来的な判断の指針とするものです。むしろ、今苦しんでいる技術的負債を別のチームが再生産しないように、という意図で書かれたセクションもいくつかあります。
+
+# 実際の例
+
+[HTTP メソッド](https://future-architect.github.io/arch-guidelines/documents/forWebAPI/web_api_guidelines.html#http%E3%83%A1%E3%82%BD%E3%83%83%E3%83%88%E3%82%99) だけで 10 個のサブセクションがあります。
+
+### [2. 複雑な検索条件が必要な場合にPOSTを用いてよいか](https://future-architect.github.io/arch-guidelines/documents/forWebAPI/web_api_guidelines.html#%E8%A4%87%E9%9B%91%E3%81%AA%E6%A4%9C%E7%B4%A2%E6%9D%A1%E4%BB%B6%E3%81%8B%E3%82%99%E5%BF%85%E8%A6%81%E3%81%AA%E5%A0%B4%E5%90%88%E3%81%ABpost%E3%82%92%E7%94%A8%E3%81%84%E3%81%A6%E3%82%88%E3%81%84%E3%81%8B)
+
+本ガイドラインでは、基本的に GET を推奨します。「クエリパラメータで表現することが難しい」「複数の検索キーがあり、長大」「クエリに秘匿情報を含み、ログに残したくない」場合は POST でもよいです。
+
+一方で、POST を使うのがよいケースにおいて GET の body にパラメータを指定する方法は非推奨です。HTTP ソフトウェアによって無視、拒否されうるためです。
+
+### [5. RESTで表現できないRPC的な操作の場合](https://future-architect.github.io/arch-guidelines/documents/forWebAPI/web_api_guidelines.html#rest%E3%81%A6%E3%82%99%E8%A1%A8%E7%8F%BE%E3%81%A6%E3%82%99%E3%81%8D%E3%81%AA%E3%81%84rpc%E7%9A%84%E3%81%AA%E6%93%8D%E4%BD%9C%E3%81%AE%E5%A0%B4%E5%90%88)
+
+`copy` のようにHTTPメソッドで表現できない処理をカスタムメソッドで表現する場合です。
+
+できる限りHTTPメソッドによる表現で対応するように努めたうえで、なお不可能な場合は `POST /drafts/{draft_id}/copy` のようなパス表現を使うことを推奨します。ただし、権限モデルや業務ロジックの複雑さ、あるいは要員の問題など、様々な理由でそもそも REST 志向を貫くことが難しい場合も考えられます。その場合は最初から RPC として [すべて POST にする判断](https://future-architect.github.io/arch-guidelines/documents/forWebAPI/web_api_guidelines.html#%E5%85%A8%E3%81%A6post%E3%83%A1%E3%82%BD%E3%83%83%E3%83%88%E3%82%99%E3%81%AB%E7%B5%B1%E4%B8%80%E3%81%99%E3%82%8B%E8%A8%AD%E8%A8%88%E5%88%A4%E6%96%AD) をしたほうがよいかもしれません。
+
+### [8. DELETEで204 No Content 以外を返すべきかどうか](https://future-architect.github.io/arch-guidelines/documents/forWebAPI/web_api_guidelines.html#delete%E3%81%A6%E3%82%99204-no-content-%E4%BB%A5%E5%A4%96%E3%82%92%E8%BF%94%E3%81%99%E3%81%B8%E3%82%99%E3%81%8D%E3%81%8B%E3%81%A8%E3%82%99%E3%81%86%E3%81%8B)
+
+DELETE ではエンティティを返すべきでない、とされることがありますが、我々は「返すべきケースもある」と考えます。
+
+本ガイドラインの前提として、業務システム向け Web API 提供である── つまり、SSKDs（Small Set of Known Developers）が対象です。限られたフロント側処理において、なにかリソースを応答して嬉しいことがあれば素直に返す方が良いです（例えば、何個消えたよ、など）。
+
+現実的には、削除を含む更新処理の後に画面表示のため再度GETしているパターンも多く、そういう場合はわざわざお節介にしてあげる必要もないので 204 でよいでしょう。いずれにせよフロントエンドとの相談になります。
+
+# まとめ
+
+紹介した内容は全体のごく一部です。皆さんも是非リンクを押して、興味があるセクションから読んでみてください。読み物としても大変面白く仕上がっていると思います。私は非推奨なコードをリポジトリに残した過去の自分に、このガイドラインを突き付けたくなりました。
+
+本ガイドラインは初版の公開後も社内のフィードバックを受けて少しずつ改訂、追補されています。皆様の開発の一助になりましたら幸いです。