webAPIの仕組みを理解する

現場で役立つシステム設計読んでのめも

データを取得するGET

基本的には対処のリソースを一意に指定する識別番号や、リソースのグループを指定するカテゴリー名はクエリパラメーターよりも、URIのパスで表現すべき。また、省略できない必須の条件もURIで指定した方がいい。
クエリパラメーターは、オプショナルなオプショナルな絞り込み条件として使うのは基本の用途。クエリパラメーターがずらずらと並ぶAPIは意図が理解しにくく、間違いも起きやすくなる。

データを登録するPOSTとPUT

相手のアプリケーションの登録を依頼する方法はPOSTとPUTの２種類で、POSTを「新規の登録」、PUTを「更新」という説明を見かけるが、本来どちらも登録。

メソッド	対象の指定方法	説明
POST	books	書籍データを登録し、識別番号を発行してもらう
PUT	books/1234	識別番号1234の書籍データを登録する

POSTはデータを受け取ったアプリケーション側でデータ(リソース)の識別番号を発行するが、PUTは要求する側が指定する。存在しない場合は新規に作成し、ステータスコード201Createdを返す。存在した場合は既存のデータを上書きし、ステータスコード200OKまたは204Not Contetを返す。

PUTでは登録を要求する側のアプリケーションが、依頼される側のアプリケーションのリソースの識別体系を事前に知っている必要がある。
この、「識別形態を事前に知っているかどうか」の違いが、アプリケーションの独立性に影響する。接続先の識別体系を知っている必要がある分、PUTはPOSTに比べて結合が密になる。
データの登録はできるだけPOSTで行うべき。その方が独立性が高くなり、将来の修正や拡張の影響を小さくできる。
PUTには返すべき応答内容の規定もなく、成功した場合に複数のステータスコードを選択できる。このため、応答内容をどうするかの決めごとが必要になる。こういう決め事が多くなるほど、アプリケーション間の連携は密結合になり、APIの修正や拡張が難しくなる。

更新の依頼もPOSTを使う

https://api.example.com/books/1234/updates

実際にどう更新するかはWebAPIを提供する側のアプリケーションの責任。books/1234が実際に上書き更新されるかもしれないし、books/1234以下に新しい書籍データが履歴として追加されるかもしれない。
このように、登録時の管理はWebAPIを提供する側のアプリケーションに任せるとで、アプリケーション間の独立性が高くなる。PAIの修正や拡張がやりやすくなる。
データの登録と相手の状態を同時に扱うPUTよりも、POSTにより登録とGETによる状態の取得を組み合わせることが、アプリケーション間の依存度を下げる好ましい設計。

DELETEを使ったリソースの削除

deleteもput同様にアプリケーション間の依存性を強くする。DELETEを要求する側と応答する側に、削除に関するさまざまな決め事が必要になる。

• 削除の実際のタイミング
• 削除の妥当性のルール
• 削除がうまくいかなかった場合の挙動

こういう決め事を詳細にすればするほどアプリケーションが密に結合し、変更がやりにくくなる。これを避けるには、以下のURIに対してPOSTメソッドで削除を依頼する方法がある。

https://api.example.com/books/1234/deletions

この方法だと、削除をどう実行するかの判断や、どのようにデータの削除を実現するかは依頼を受け取ったアプリケーションの責任になる。APIを利用するがわは、削除の「依頼」ができるだけ。こういう設計にすることで、アプリケーション間の依存関係を小さくできる。

エラー時の約束事

コード	テキスト表現	説明
400	Bad Request	要求が不正
403	Forbidden	要求は禁止されている
404	Not Found	要求さえれたリソースが見つからない
500	Internal Server Error	エラーが起きたため要求を正しく処理できなかった

ステータスコード４００番台は利用する側に問題がある。どのように対応するかは利用側の役割。
５００番台が帰ってきた場合、基本的には利用する側で対応できることはない。