Subscribed unsubscribe Subscribe Subscribe

@kyanny's blog

Write down what I learnt. Opinions are my own.

APIs: A Strategy Guide を読んだ

APIs: A Strategy Guide を読んだ。

この本は API の設計や実装に関する本ではない。もっと大局的な、 API を取り巻くエコシステム全体のあり方を論じる本だった。要するに、開発者視点では得るものが少なかった。とはいえ一ヶ月半近くかけて主に通勤中に、最後のほうはすっとばしながら、無理やり読んだので章ごとのざっくりしたまとめと感想を書く。

Chapter 1 The API Opportunity

そもそもなんで API があると良いのかについてビジネス的な視点で触れている。スマートフォンのようなリッチなモバイル端末が世界中で爆発的に普及しているのでさまざまなデバイス向けに素早くコンテンツを提供できるかどうかが重要になる、そこで API ですよ、という流れ。

あと一般に API というと一般に公開してサードパーティの開発者に利用してもらう public API を想像しがちだけど、一般公開はせず社内で部署をまたいで利用したりパートナー企業に提供したりする private API をつくることはもっとインパクトがあるんだよ、という点にも触れている。

private API というやつは言われなくてもやってるよ、というところも多いと思うけど、あえて名前をつけて public API とは違うものなんだよ、と名前をつけることには認識上一定の価値がある気がする。

Chapter 2 APIs as a Business Strategy

API はビジネス戦略上重要になりうるんだ、という退屈な話。

Chapter 3 Understanding the API Value Chain

API によって誰が嬉しくなるのか、そこをちゃんと考えましょうね、という退屈な話。コンテンツホルダーAPI パブリッシャー、デベロッパー、エンドユーザー、などの登場人物がそれぞれ Win-Win になるようにしましょうね、など。 private API を社内の開発者に利用してもらうためには継続的な布教活動が大事だよ、などと涙ぐましいコメントもある。肝心のデータに価値がなければ API 公開しても無意味だよ、とか。

Chapter 4 Crafting Your API Product Strategy

似たような話が続く...。 API を開発・運用・広報などするチームのメンバーにはどういう役割のひとたちが必要か、具体的にどういう役割を果たすのか、という話。よほど巨大な企業を想定しているのか、役割がやけに多くて細かい(ある程度は兼任も想定されているみたいだけど)エヴァンジェリストとかコミュニティマネージャと呼ばれるような人は重要だし、運用に携わる人も重要だよ、と(開発者はいないと API 実装できないのでわざわざ触れるまでもないよね、的な扱い)

Chapter 5 Key Design Principles for APIs

やっとテクノロジーっぽい話題に入る。 API のデザインの話。ここで Pragmatic REST という言葉がでてくる。この話題がこの本のなかで一番ためになったと思う(それくらいしかなかったというほうが正しい) API はとにかく覚えやすく、すぐ試して使えるようにしろ、と。長大なドキュメントを読まなくてもカンで呼び出せるほうがいいし、 API Explorer 的なものを用意してブラウザですぐ実行できる環境を用意すると開発者に選んでもらえやすい(ただしコンテンツが一番重要というのは覆せないけど)

Pragmatic REST について詳しく。まず Pure REST に触れて、 Hypermedia as the Engine of Application State (HATEOAS) という原則はきれいだけど実際には必ずしも扱いやすいとは言えない、しかし REST の HTTP との親和性の高さは捨てがたいのでいいとこ取りしましょう、という結論に至る。 PureREST のどこが扱いづらいか、というのも割合細かく触れられていて、読解に自信がなくうまく書けないのだけど、

GET http://api.myapi.com/
# welcome document が返されて、利用できるリソースの URI が記載されている


GET http://api.myapi.com/customers
# 上のリクエストをする前にいきなり /customers という URI へリクエストするのは HATEOAS の思想的には誤り
# ... とはいえ現実にはこの程度ならハードコーディングしてしまって API の URI を固定するほうが利用しやすいし、
# モバイル端末などリクエスト回数が増えるデメリットが激しい場合は最初のリクエストは無駄ともいえる

ということだと思う。あとまあ REST vs SOAP みたいなのはもういいよね、という感じでさらっと流していた。あと XML vs JSON もまぁ JSON でいいよね、という感じ。

それから API のバージョンについて、これも大事な話題だった。バージョンをわけるなら URI に入れればいいが、新バージョンに変更することが難しいケースもある(組み込み機器など)著者は Netflix の API に関わっていて、たとえばテレビとか動画を再生する機能つきのハードウェアに組み込んだソフトウェアは気軽に API の URI を書き換えられないのでバージョンレスな API が必要だ、と説く。そのような場合、テクニックのひとつとして、

<home_phone_number>03-5456-2622</home_phone_number>
# 新しいキーが増えたとき困る。 "未知のデバイス_phone_number" など


<phone_number type="home">03-5456-2622</phone_number>
# type 属性値に任意の値が入れられるので未知の type にも対応可能

なんていう例が挙げられている。 URI and response formats should be generic where possible. と。

あとは API のインフラまわりをどうすべきか、などの話で、特に示俊にとむ話題はなかった。

Chapter 6 API Security and User Management

Identification と Authentication の話。ここも読み応えがある章。 API キーなり Basic 認証なり OAuth なりで「誰が」 API を利用しているのか特定する必要があるよね、 API キー方式だと quota みたいなものを個別に適用しやすいよね、その場合 API キーの盗聴を防ぐために SSL 通信を導入できるといいね、あとデータそのものの暗号化が必要ならそれに適した技術もあるよ、など。

Chapter 7 Legal Considerations for Your API Strategy

「利用規約に同意」とか「プライバシーポリシー」とかそういう話題。このへんで一度読むのを挫折しかけた。短い割に読むのがきつい内容だけど、法務部門があるような会社で認識のズレから不要な対立をせずに済むために開発者側がある程度そのへんも頭の片隅にとめておく意義はあるのかなと思った(法律関連のことは丸投げ、という姿勢でいたら業界のデファクトスタンダードやら慣習やら空気感やらを全然知らない担当者が斜め上の利用規約を制定してしまってゴタゴタする、みたいなのを未然に防げるかもしれない)

Chapter 8 Operating and Managing an API

API の運用の話。ふつうのウェブサイトの運用とあまり変わらない気がする。パートナーに提供する private API の場合は契約的な側面が強くなるので SLA どこまで保証するのかなども実運用開始前にちゃんと考えておこうね、など。あと https://status.heroku.com/ みたいなページがあるといいね、と。

トラフィックをどうさばくか(もしくはさばかず拒否するか)の話題で Quota とか Throttling とか Rate Limits に触れている。これらの制限はビジネス上の理由でもって実施されるものですよね、という論調(制限を緩めるためにはお金を払ってもらう、というビジネスモデルもありえるということ)

あとこの手の制限では厳密にはケアしきれないのが、非常に重い処理を実行するリクエストと軽いリクエストがどちらもリクエスト回数としては同じ一回になるので不公平じゃね?という問題提起もある(解決方法は提示されない)

Chapter 9 Measuring the Success of Your API

API が成功しているかどうか計測して数字でわかるようにしましょう、という話。特筆すべき点なし。

Chapter 10 Engaging Developers to Drive Adoption

外部の開発者をやる気にさせて引き込むにはどうすればいいのか?という話。使い勝手の良いデータを提供しろとか API を簡単に使えるようにとか何度か出てきた話題にくわえて、 API 提供者側へコンタクトするチャンネルをいくつか用意しておけとか、逆に開発者のコミュニティに参加して意見を募れとか。コミュニティ内で影響力のつよいキーパーソン、アルファギークと親密に付き合って意見をもらったりするといいよ、とか。あと Developer Portal は必要だよね(フォーラムもね)

Chapter 11 Epilogue: Just the Beginning

むすびのことば。 API 重要。さあいまからはじめよう。

このブログエントリのまとめ

O'Reilly Media の Deal/Day: Save 50% で売りだされてたタイミングで買ったので $9.99 ですんだけど、これを定価の $19.99 で買っていたらだいぶガッカリしたと思う。紹介ページに記載の内容にはまじめに目を通して、著者の経歴がすごそうだから期待できそうだぞと思ったり、冒頭部分を試し読みもして悪くなさそうだなと踏んで買ったけど、期待した内容とはずいぶん違っていた。

英文じたいは平易というか短調で、同じような単語ばかり出てくるので辞書引く回数が減って楽だとおもいきやだんだん飽きてくる(!)という事態におちいって、さっさと次へいこうかと思ったけど、主語が長い文章がけっこう多く出てくる気がしたので途中から英文読解の勉強をするつもりで内容そっちのけで読んだ。

おすすめはしませんがアフィリエイトのリンクは貼っておきます。