感想

web APIの設計をするときに意識するべきことが、大手webサービス(Facebook, Twitter, Instagram, etc)のAPIと比較して書いてあり、これを読めば自分のサービスに合った設計ができるようになっていると感じた。

例えば自分が初めてAPIを設計しようと考えた時、自分が今までに使ったことのあるAPIを振り返ったりして、良いところや悪いところを参考にしながらつくろうとするはずで、それぞれの設計の意図やその比較がこの本のようにまとまっているのはとても分かりやすいと思う。

また、比較的新しい(2014に発表された)設計思想などにも触れられており、従来のパターンだけではないAPIを設計するヒントにもなるだろう。

以下備忘録として、三つ気になったポイントを書いておく。これらの他にも様々な項目について記載されているので、APIを設計するにあたって何かしら新しい気づきがあると思う。

対象となる開発者の数とAPIの設計思想について

APIの設計思想は、誰でもが使えるように広く公開するAPIと、そうでないAPIとで異なるという話があった。

具体的な例として、Eコマースサイトのスマートフォン向けのアプリケーションを作る為のAPIの設計の例が挙げられている。

このアプリのホーム画面で使いたい情報が、「新着の商品」、「人気の商品」、「ログイン中のユーザ情報」、「購買履歴に基づくレコメンド」など様々であったとき、一般的な方法に基づいてそれぞれの機能ごとのエンドポイントを持ったAPIをつくることが最良とは言えない。

ホーム画面で表示する情報をひとつにまとめた”ホーム画面表示用API”を作成したほうが、クライアントアプリを作る開発者にとって、確実に利便性が高いだろうという話だ。

HATEOASについて

HATEOAS (Hypermedia as the engine of application state)は、APIの返すデータの中に、次の行動、取得するデータ等のURIをリンクとして含めることで、そのデータを見れば次にどのエンドポイントにアクセスすればよいかがわわかるような設計のこととされている。

具体的な例として挙げられているのが、友達一覧のデータを取得するAPIがあったとき、そのレスポンスの中に友達の名前とともに、それぞれの友達の詳細を取得するためのuriを入れておくというような設計だ。

{
  "friends":[
    { "name": "Saeed",
      "link": {
        "uri": "https://api.exmaple.com/v1/users/12345",
        "rel": "user/detail"
      }
    },
    { "name": "Jack",
      "link": {
        "uri": "https://api.exmaple.com/v1/users/6789",
        "rel": "user/detail"
      }
    },
...
...
  ]
}

この友人の詳細情報を取得するuriをたたくと、今度はその友人とやりとりしたメッセージを取得するuriや、友達関係を解消するuriを含んでいるかもしれない。

性別のデータをどう表すかについて

以前であれば生物学的な性別のみで、男性と女性とを1と2の数値で表すこともあったが、近年では社会的/文化的性別を選択可能にしているサービスも増え、性別を文字列で扱うところが圧倒的に多いとしている。

なかでもFacebookは2014年の2月に、選択可能な性別を一気に50種類以上に増やしたそうだ。

ただ、生物学的な性別が必要な、例えば医療系のサービスもあるので、適切なものを選択していく必要がありそうだ。