Web APIの設計

第二章　ユーザーを意識したAPIを設計する

プロバイダ目線ではなく、ユーザー目線で設計する

• プロバイダ目線だと内部システムをユーザーに晒すことになり、ユーザーが使いづらくなる。
• APIを設計する際は「何を」と「どのように」を明らかにする

第三章　プログラミングインターフェースを設計する

HTTPの基本原理

• HTTPはプログラミング言語に依存しないプロトコルであり、アプリケーション同士がインターネットを介してドキュメント（リソース）をやり取りできるよう、設計されている
• HTPPメソッドはパスによって識別されたリソースをどのように処理するかを示している。

リソースをパスで表す

• パスの設計において最も広く採用されているのは以下のフォーマットである。
  /{コレクションのアイテムの種類を表す複数形の名前}/{アイテムのID}
  このフォーマットはアイテムがコレクションのアイテムの種類が明確になる。

アクションをHTTPプロトコルで表す

• GET・・・/products/{productID}というパスを使い、リソースの内容を返す
• DELETE・・・/products/{productId}.　情報は返さない
• PATCH・・・リソースの部分的な更新に使う。情報は返さない
• PUT・・・リソースの置き換えを行う。リソースが存在しない場合は新たに作成し、作成されたリソースを返す。そうでない場合は、情報を一切返さない

リソースの設計

1. まずデータ構造のプロパティをリストアップし、それぞれに名前を付ける。
2. プロパティごとに以下の特性を集める
   • 名前
   • 型（プログラミング言語に共通する移植可能なデータ型のみを使う）
   • 必須かどうか
   • 説明（オプション）

第5章 単純明快なAPIを設計する

単純明快な表現を設計する

例えば、bkAccOverProtFtActBlnというプロパティがあるとする。これは非常にわかりにくい。そこで、ユーザーにとって扱いやすいプロパティ名に直していく。

1. 略語は慣用的なもの以外使わない
   bkやAccなどの略語は意味が分かりにくいので使ってはいけない。使ってい良いのはminやmaxなど慣用的に用いられているものだけである。この原則からプロパティ名はbankAccountOverdraftProtectionFeatureActivateBlnとなる。
2. 余計なサフィックスをつけない
   booleanという内部のコーディング規約をさらしてはいけない上に、ドキュメントにbooleanと記載があるならばプロパティ名にそれを含める必要なない。同様に最後のActiveもいらない。以上より、プロパティ名はbankAccountOverdraftProtectionFeatureとなる
3. 必要のない言葉を入れない
   Featureという単語をわざわざ入れなくてもこのAPIが銀行口座のサービス（機能）であることは明らかなのでいらない。bankAccountOverdraftProtectionとする。
4. スキーマの単語をわざわざ入れる必要はない。overdraftProtectionとする。

以上で、最初は7つだった単語が2つに減った。

第8章　セキュアなAPIを設計する