Open2
Web APIの設計
silva第二章 ユーザーを意識したAPIを設計する
プロバイダ目線ではなく、ユーザー目線で設計する
- プロバイダ目線だと内部システムをユーザーに晒すことになり、ユーザーが使いづらくなる。
- APIを設計する際は「何を」と「どのように」を明らかにする
silva第三章 プログラミングインターフェースを設計する
HTTPの基本原理
- HTTPはプログラミング言語に依存しないプロトコルであり、アプリケーション同士がインターネットを介してドキュメント（リソース）をやり取りできるよう、設計されている
- HTPPメソッドはパスによって識別されたリソースをどのように処理するかを示している。
リソースをパスで表す
- パスの設計において最も広く採用されているのは以下のフォーマットである。
/{コレクションのアイテムの種類を表す複数形の名前}/{アイテムのID}
このフォーマットはアイテムがコレクションのアイテムの種類が明確になる。
アクションをHTTPプロトコルで表す
-
GET・・・/products/{productID}というパスを使い、リソースの内容を返す -
DELETE・・・/products/{productId}. 情報は返さない -
PATCH・・・リソースの部分的な更新に使う。情報は返さない -
PUT・・・リソースの置き換えを行う。リソースが存在しない場合は新たに作成し、作成されたリソースを返す。そうでない場合は、情報を一切返さない
リソースの設計
- まずデータ構造のプロパティをリストアップし、それぞれに名前を付ける。
- プロパティごとに以下の特性を集める
- 名前
- 型（プログラミング言語に共通する移植可能なデータ型のみを使う）
- 必須かどうか
- 説明（オプション）