Web API The Good Parts を読んで

• (予習)その本にかける時間を決める (20h)
• (予習)本から学びたいことを書き出す (Web API の設計の知識をつける, API の「こうあるべき」を知る)
• (予習)胡散臭い人に書かれたと考える
• (復習)仮説を作り、検証する
• (復習)自分の行動の変化を書き出す
• (復習)記事を書くか、人に話す

なぜ Web API の設計が重要なのか

• Web API を公開することは、利益に加えて色々な付加価値をサービスに加える
  　- 公開された API を利用した新しいサービスが生まれたり、逆にそのサービスを本家の機能に取り入れたり
• 公開するとなった時に、以下の理由から美しい設計である方が良い
  • 利用者にとって使いやすいか
  • API の変更をしやすいか
  • セキュリティ面が考慮されているか
  • 公開して恥ずかしくないクオリティか

美しく設計するための原則

• 仕様が決まっているものに関しては、仕様に従う
• 仕様が決まっていないものに関しては、デファクトスタンダードに従う

REST とは

1. RPCスタイルに合わせた簡易なXML + HTTPインタフェースを採用したシステム（SOAPは使わない）
2. Roy Fielding のRESTアーキテクチャスタイルの原則に合わせたWebサービスシステム

LSUDs と SSKDs

LSUDs (Large Set of Unknown Depelopers) :

• 公開されていて誰でも使えるAPI
• 例: Twitter, Facebook

SSKDs (Small Set of Known Depelopers):

• 非公開で利用者が限られているAPI
• 例: 自社サービス向けのAPI

検索とクエリパラメータの設計

リソースの名前の注意点

• 複数形の名詞を使用する
  • データベースのテーブル名が複数形を使うのと同じく、URL のエンドポイントはリソースの「集合」を表しているため
    • そもそもなぜ名詞なのか
      • HTTP の URL がリソースを表すという考え方から、捜査の対象であるリソースは名詞であるべき
      • hTTP のメソッドが動詞を表すものであり。動詞 + 名詞の組み合わせを使うことで、最もシンプルにやりたいことを表現できるから
• 一般的な単語をつける
• スペースやエンコードを必要とする文字を使わない
  • そのエンドポイントの意味が理解しにくい

ページネーションに相対位置 (Limit / Offset) を使うときの注意点

• 必要なページにたどり着くまでに、最初からそこまでの全ての行を数える必要があるため、後のページになればなるほど応答速度が遅くなる
• 更新により表示内容がずれることがある
  • 最初の 20 件を表示 -> 誰かが次の 20 件の内容を更新 -> 次の 20 件を表示 --- 最初のページの末尾のレコードが次のページの先頭にも表示される

対策 : 絶対位置 (Seek) によるページネーション

• 先頭から数えて難件、という取得方法ではなく、指定した ID よりも前・後という方法で指定する
  • 取得したデータのうち最後のものの ID や時刻を条件に「この ID よりも前のもの」という形で指定する￥

クエリパラメータとパスパラメータの使い分け

あるパラメータをクエリパラメータとするかの考え方

• 一意なリソースを表すのに必要な情報かどうか
  • 例えば、http://api.example.com/v1/users/ の users がないとその API はどんな情報を返すかわからない
  • アクセストークンなどのパラメータは利用者の認可が目的なので、そのリソースを表すのに必要な情報ではない。つまりクエリパラメータで良い
• 省略可能かどうか
  • limit, offset など、省略するとデフォルトの値が利用されるようなもの

ログインと OAuth2.0