『Web API - The Good Parts』読後メモ

『Web API - The Good Parts』を読んだので，備忘録としてメモしていく．

訳書かと思って身構えていたけれど，和書だったので安心．

レスポンスデータのデータフォーマット

APIによっては，(XMLとJSONとのように)2つ以上のフォーマットでレスポンスデータを表現したい場合もある．そういった場合の対応はいくつかあるが，僕がよく見たことがあるのは，URLの末尾に.xmlや.jsonのように，あたかもファイルシステムの拡張子のようにファイルの種類を表記する文字列を追加する手法だ．これは直感的だが，複数のURLが実質1つのデータを表現するために存在しているのは不自然だとも感じていた．

この表記について，本書は『データフォーマットの指定方法*1』にて，一般的な手法として「クエリパラメータを使う方法」，「拡張子を使う方法」，「リクエストヘッダでメディアタイプを指定する方法」にそれぞれ触れつつ，以下のように述べている．

筆者としては1つだけを選ぶならURIでクエリパラメータを使う方法を、複数選ぶならメディアタイプをヘッダで指定する方法を両方サポートする、という方法をおすすめします。

僕はHTTPの上に何を流すのかに注目していたため，ヘッダを使うという方法(HTTP Content Negotiation)があることにそもそも気付かずにいたので，ヘッダを使うシンプルな手法に強く惹かれたが，アプリケーションからヘッダを扱うやり方は，サーバにとってもクライアントにとってもクエリパラメータを使う方法や拡張子を使う方法ほどお手軽ではない((Play framework 2.5.xでは，コントローラでフォーマットを定義するとplayが自動的にAcceptヘッダをさばいてくれる． https://www.playframework.com/documentation/2.6.x/ScalaContentNegotiation))ように思えたし，本書でも「メディアタイプを指定する方法はHTTPの仕様には最もあった方法だといえますが、URIだけで指定できるほうが手軽であり見た目にわかりやすく、さらに初心者にやさしい」としている．

そもそもふだんの開発であまりHTTPヘッダを意識することはなかったので，もっと勉強していこうという気になれた．

件数を返すAPI

あるリソースの数量を計数して返すようなAPIを用意したいとき，これはどういったURL(もしくは他の手段)でアクセスすればよいだろう．

本書では(件数そのものが目的ではなく)配列などに加えてさらにその件数(長さ)を返したいときの留意点として，「全体の件数を計算する処理は重くなりがちで工夫が必要になるので、本当に件数を返すことが必要であるのかをしっかりと見極めたほうがよいでしょう*2」と述べている．

さて困ったことに，配列などのついでに件数も返すのであればURLは元々の配列などのリソースによって決まるが，件数そのものが目的であるときのURLはどう表記したものかと思った．僕が見たことがあるのはhogehoge.countという.countを接尾語とする手法で，これは「拡張子を使う方法」にならっているようだ．つまり件数はフォーマットの一種だと解釈している．だがある意味で件数は二次的な情報であって，そのためにリソースを用意するのも問題は無さそうに思える．

件数はリソースのフォーマットの1つである (e.g. /friends.count)
件数はそれ自体が独立したリソースである (e.g. /friends/count or /count/friends)

僕は，件数は「個数を取るという関数」でリソースを表現したものだといえるから，リソースのフォーマットとして解釈したほうが良いのかな，と思ったが，完全に納得いく答えは出ずにいる．

エンベロープ

エラーを返したいときに，何にアクセスしてエラーになったのかだとか，データそれ自体には関係無いが，付随して渡したほうがデバッグが楽になるようなデータだとか，そういったメタ的なデータもついでに送りたいことはよくある．

そこで手軽な手法として，データをさらに別の構造に包んで返すといったことが行われる．例えば以下のように．

{
  "header": {
    "error": false,
    "errorCode": "0"
  },
  "data": {
    ...
  }
}

これはエンベロープ(封筒)と呼ばれる手法で，冗長な表現であるためやるべきではないという．なぜなら，HTTPにはメタ情報を送るためのヘッダが元々あるのだから，(既に用意された手段に従って)それを使うべきだというわけだ．しかしこれにも欠点があって，ヘッダにメタ情報が格納してあっても，事情を知らないと一見わかりにくい．これは慣れの問題だと言えそうだが，現状でHTTPヘッダはそれほどメジャーだとはいえないようなので，不慣れなエラーを防ぐためにちゃんと周知したほうがよさそうと思った．