Web API the good parts

エンドポイントの基本的な設計

覚えやすく、どんな機能を持つURIなのかがひと目でわかる
  • 短くて入力しやすいURI
  • 人間が読んで理解できるURL
  • 大文字小文字が混在していないURI
  • 改造しやすい（Hackableな）URI
  • サーバー側のアーキテクチャが反映されていないURI
    • どんなソフトウェア、言語を利用しているのか。
    • ディレクトリやシステム構成がどうなっているのか。
  • ルールが統一されたURI
リソースにアクセスするための設計の注意点
  • 複数形の名詞を利用する
  • 利用する単語に気をつける
  • スペースやエンコードを必要とする文字を使わない
  • 単語をつなげる必要がある場合はハイフンを利用する

リソースの一覧取得のエンドポイントが検索を兼ねる。 絞り込み検索はパラメーターを設定する。

検索に相対位置を利用する問題点

データ数が膨大になるとpageやoffsetを指定されていると「先頭から何件目か」を調べるために先頭から数を数える処理が行われるため遅くなる。 また、更新頻度が高いデータの場合データに不整合が生じる。

絶対位置でデータを問題点

絶対位置指定とは、オフセットで相対位置を指定する代わりに、これまで取得した最後のデータのIDや時間を記録しておいて、「このIDより前のもの」や「この時刻より古いもの」と言った指定を行う方法。　

配列とフォーマット

オブジェクトで配列を包むメリット
  • レスポンスデータが何をしていものかがわかりやすくなる
  • レスポンスデータをオブジェクトに統一することができる。
  • セキュリティ上のリスクを避けることができる

トップれべるが配列であるJSONは、JSONインジェクションに対するリスクが大きくなる。

続きがある場合どうデータを返すべきか

例えば20件データを返すためには最大21件の取得を行ってみて、実際に21件取得できれば、 「hasNext」といった名前で結果を含めてあげれば良い。