REST API Design Best Practices — txt1.ai

マーカス・チェン氏による、フィンテックとヘルスケア企業で14年間スケーラブルなシステムを構築してきた首席APIアーキテクト

3年前、私はスタートアップがAPI設計の根本的な欠陥により、230万ドルのエンジニアリングコストを消耗しているのを目撃しました。彼らは47の異なるエンドポイント、一貫性のない命名規則、バージョニング戦略のない決済処理システムを構築していました。最大の顧客のために新しい機能を追加する必要があった時、変更はドミノのようにシステム全体に連鎖しました。6ヶ月間のリファクタリングの後、彼らは最大の顧客を失い、エンジニアリングチームの40%を解雇しました。

その災害は、私に重要なことを教えてくれました。API設計は、単に今日機能するものを作ることではありません。時間が経っても優雅に進化し、数百万のリクエストを処理し、開発者が実際に使用したいと思うような直感的な契約を構築することです。年間数十億のトランザクションを処理するAPIを設計して10年以上が経ち、良いAPIと優れたAPIの違いは、ほとんどのチームが見落とす基本的な原則の数に帰着することを学びました。

基礎: バズワードを越えたRESTの理解

2010年にキャリアを開始した時、RESTはすでにWeb APIの支配的なアーキテクチャスタイルでしたが、多くの開発者がそれを哲学ではなくチェックリストとして扱っていることに気付きました。RESTは表現状態転送（Representational State Transfer）の略で、ロイ・フィールディングが博士論文で概説した6つのコア制約に基づいています。しかし、実際に重要なことは、RESTはAPIリソースを名詞として扱い、HTTPメソッドを動詞として使用し、ステートレス性を維持することです。

ステートレス性の原則だけでも、私は数え切れないデバッグ時間を節約できました。クライアントからサーバーへのすべてのリクエストには、そのリクエストを理解し処理するために必要なすべての情報が含まれていなければなりません。サーバー上にはセッション状態がありません。これは、あなたのAPIが複雑なセッション管理なしで水平にスケールでき、クラスター内の任意のサーバーが任意のリクエストを処理できることを意味します。3.2百万のトランザクションを毎日処理する医療プラットフォームの決済APIを設計したとき、この原則により、アプリケーションコードの1行も変更することなく、ピーク時には4台から47台のサーバーにスケールすることができました。

しかし、RESTは教条主義ではありません。私は、あるものが「真にRESTful」であるかどうかについて何週間も議論しているチームを見てきましたが、彼らは整合性と使いやすさに焦点を当てるべきです。目標は、開発者が直感的に理解できるAPIを作成することです。HTTPメソッドを正しく使用し、リソースを論理的に整理し、ステートレス性を維持しているなら、あなたは90%のところまで来ています。残りの10%は、APIを使う喜びにするための実践的なパターンについてです。

リソース名付け: 直感的なURLのアート

あなたのURL構造は、開発者が最初に目にするものであり、API全体の期待を設定します。私は単純なルールに従っています: リソースには名詞を使用し、複数形にし、明確な親子関係がある場合は階層的に整理します。例えば、/api/v1/users/12345/orders/67890は、すぐにユーザー12345に属する注文67890を見ていることを示します。

"最高のAPIは、開発者がドキュメントを読む前に次のエンドポイントを予測できるものです。それが真の一貫性を達成したことを示します."

ほとんどのチームが間違えるのはここです: 彼らはURLに動詞を混ぜ込みます。私は、/api/getUserや/api/createOrderのようなエンドポイントを持つAPIを見てきました。これは冗長で、HTTPメソッドがすでに動詞を提供しているからです。GET /api/users/12345は、GET /api/getUser/12345よりも明確でよりRESTfulです。HTTPメソッドが実行しているアクションを示し、URLが操作しているリソースを示します。

整合性は完璧さよりも重要です。あるプロジェクトでは、リソースのユーザー用に/usersと/accountsのどちらを使用するかについて議論がありました。その会議で3時間を費やしました。重要なのは、どの用語を選択したかではなく、1つを選んでAPI全体でそれに固執することでした。私たちは決定を書き留め、それをAPIスタイルガイドに追加し、先に進みました。その整合性は、開発者がドキュメントを常に確認することなくエンドポイント名を予測できることを意味しました。

ネストされたリソースについては、深さを最大2〜3レベルに制限します。それ以上になると、URLが扱いにくくなり、関係が不明確になります。もし/api/companies/123/departments/456/teams/789/members/012のようなものを書くことになったら、行き過ぎています。その代わりに、チームをトップレベルのリソースにし、クエリパラメーターを使用することを考えてください: /api/teams/789/members?company=123&department=456。これにより、URLを管理可能に保ちながらも、リソースを適切にフィルタリングおよびスコープ設定できます。

HTTPメソッド: 適切なツールを使う

HTTPは私たちに豊富なメソッドの語彙を与えていますが、私は開発者がこれらを一貫して誤用するか、GETとPOSTに制限しているのを見ています。各メソッドの意味を理解することは、直感的でキャッシュ可能なAPIを構築するのに役立ちました。GETはリソースを取得し、冪等性があり、安全でなければなりません—複数回呼び出しても、同じ結果を生成し、副作用はありません。POSTは新しいリソースを作成します。PUTはリソース全体を置き換えます。PATCHはリソースの一部を更新します。DELETEはリソースを削除します。

PUTとPOSTの冪等性は信頼性にとって重要です。847店舗の小売チェーン向けに在庫管理APIを構築したとき、冪等性の保証のために特に更新にPUTを使用しました。ネットワークの問題でリクエストが2回送信された場合でも、PUTにより重複レコードが作成されたり、同じ更新が何度も適用されたりすることがありませんでした。この単一の決定は、最初の運用年で約12,000の在庫不一致を防ぎました。

PATCHはあまり活用されていませんが非常に価値があります。軽微な更新のためにクライアントにリソース全体の表現を送信させる代わりに、PATCHは部分的な更新を許可します。30のフィールドを持つユーザープロファイルを更新する場合、クライアントがメールアドレスだけを変更したいのに、すべての30を送信させる必要はありません。PATCH /api/users/12345でボディが{"email": "[email protected]"}であれば、全リソースを要求するよりも効率的でエラーが少なくなります。

DELETEも冪等であるべきです。すでに削除されたリソースにDELETEを呼び出すと、204 No Contentまたは404 Not Foundを返し、エラーは返さないべきです。これにより、リトライロジックが簡素化され、信頼性が向上します。私は、DELETEがリソースを物理的に削除するのではなく非アクティブとしてマークするソフトデリートを実装しました。これにより監査証跡が残り、回復が可能になります。要点は、同じリソースに対するその後のDELETE呼び出しが同じ結果を生成することです—リソースはクライアントの視点から消えています。

ステータスコード: HTTPの言語を流暢に話す