「Web APIの設計」読書メモ

システムの成否はAPIの設計品質に左右される。

APIはソフトウェアのWebインターフェース。

APIは何らかのソフトウェアの内部実装を抽象化したものに過ぎない。

パブリックAPI：サービスや製品として他企業が提案するもの
プライベートAPI：あなたが自分のために構築するもの

APIがパブリックかプライベートかは誰に対して提供するのかで決まる。

コンシューマの視点に立つと、APIのユーザビリティが改善される。

コンウェイの法則。
APIの設計は、そのAPIの設計をしている組織のコミュニケーション構造の影響を受けることがある。

内部のビジネスロジックを外部に公開すると、コンシューマにとってAPIが理解しにくく使いにくいものとなる。

パスの構造はファイルシステムのディレクトリ構造のようなものと考えるとよい。

/catalog/{producId}でもいいし、
products/{productId}でもいい。

RESTの一般的なフォーマット

/{コレクションのアイテムの種類を表す複数形の名前}/{アイテムなどのID}

複数形の名前を利用することはデファクトスタンダード。

resources/{resourceId}/sub-resources/{subResourceId}のように複数のレベルに拡張も可能。

/products/{productId}というパスの場合、
GET /products/{productId}ならば、取得
POST /products/{productId}ならば、作成
DELETE /products/{productId}ならば、削除
PATCH /products/{productId}ならば、更新
PUT /products/{productId}ならば、置き換え（ない場合は作成）

ゴールのパスとHTTPメソッドのペアに置き換える方法がすぐに思い浮かばない場合、アクションリソースを作成する。

アクションリソースは名詞ではなく動詞で表されるリソース。
単なる関数、クラスのメソッド。

ショッピングカートリソースを/cartで表すとき、
cart.XXX()メソッドは/cart/XXXと表せる。

スタンドアロン関数xxxCart()とみなして、/xxx-cartでも問題ない。

上記の場合は、POSTを用いること。

アクションリソースはRESTモデルに全く従っていない。
が、コンシューマにとっては完全に理解可能。

• クライアントとサーバーの分離
  • 関心を明確に分離
• ステートレス性
  • クライアントのコンテキストをサーバーは保持しない
• キャッシュ可能性
  • レスポンスを再利用できるか
• 階層化システム
  • サーバーの背後にあるインフラストラクチャは認識しない
• コードオンデマンド
  • 実行可能コードをクライアントに転送可能
• 統一インターフェイス
  • すべてのやり取りを識別されたリソースに従って行う必要がある

OpenAPI SpecificationはREST API記述フォーマットでよく知られている。

OASのライバルはRAML、Blueprint。

内部のコーディング規約が外部に漏れると途端にわかりづらくなる。

APIはユーザーインターフェース。

数値コードはだめ。
type: 1, type: 2のようなものだと、いちいちドキュメントで調べなくてはいけない。
type: checkingのように文字列とする。
上記が無理なら、typeNameのような説明用の値を追加する。

一貫性のある名前を付ける。

一度決めたルールから外れることはしない。

コンテントネゴシエーション。

OPTIONSは利用可能なHTTPメソッドを知ることができる。

データの入出力において、入れ子の深さは3程度が望ましい。

モバイルアプリケーションのプライベートAPIはハックの対象にされやすい。

クレデンシャルをコンシューマに送信させることで登録済みのコンシューマと判別できる。

最小権限の原則。
必要最低限に制限することで攻撃可能性を低下できる。

APIのゴールをスコープに分割すべき。

センシティブな内容は本当に返すべきか吟味が必要。
例えば、クレジットカードのカード番号、CVV等。

シーケンシャルなデータベースキーは返してはいけない。
顧客数などの情報を推測できるため。

パーミッションエラーなどは明言しない方が良い。
情報漏洩とみなされる可能性がある。
例えば、悪意ある第三者の攻撃だった場合、暗にそのリソースが存在することを言及しているようなものであるため、

技術スタックに関する詳細情報が露呈してはならない。
NULLPointerExceptionなど。

一度でもコンシューマが使い始めた場合は、破壊的変更を追加しない限り、設計を修正できなくなる。

新しい要素を追加することが最も安全。

解決策はAPIのバージョニング。

セマンティックバージョニング
メジャーを上げる場合は破壊的変更の時。
マイナーを上げる場合は後方互換性のある変更の時。
パッチを上げる場合は後方互換性のあるバグ修正関連の変更がある時。

APIの場合は、<破壊的>.<非破壊的>の2つだけ。

最適化の方法

• 圧縮の有効化
• キャッシュと条件付きリクエストの有効化
  • 変更があった場合のみ返す
    • HEADメソッドならば、ヘッダーのみ取得可能

フィルタリングオプション。

データの集約。

QraphQLはPOSTのみ利用する。
そのため、HTTP標準のキャッシュは不可。
※本が書かれた時点では。

完了したか問い合わせを繰り返すことをポーリング

無駄な呼び出しが多いため、双方にとってポーリングは迷惑である。

Webフックを利用すればプロバイダからコンシューマへ伝えることができる。
リバースAPIともいう。

リファレンスガイドライン
ユースケースガイドライン
設計プロセスガイドライン