どうも。Reoです。
お仕事でAPI設計の知識が必要になり、「Web API: The Good Parts」を読みました。さらっと感想を書いていこうと思います。
概要
Web APIの設計、開発、運用についての解説書。APIは設計次第で使いづらいものになってしまうだけでなく公開後の保守運用も難しくなってしまいます。そのためAPIを美しく設計することがとても重要です。本書では「設計の美しいAPIは、使いやすい、変更しやすい、頑強である、恥ずかしくない」という考えのもと、APIをどのように設計し運用すればより効果的なのか、ありがちな罠や落とし穴を避けるにはどういう点に気をつけなければいけないのかを明らかにします。
オライリーの本です。実はオライリー本を読むのは初めてかもしれない。にわかエンジニアです。
Web API にも種類がいろいろあるそうですが、その中でもターゲットは以下になっています。
ターゲットは、URIにアクセスするとXMLやJSONなどのデータが返ってくるシンプルなタイプ――XML over HTTP方式やJSON over HTTP方式――のAPIです。
よく「REST API」と呼ばれているものについては
RESTという言葉は、よく様々な公開されているAPIにおいて「REST API」という言葉で使われており、一般には「HTTPでアクセスでき、データをXMLやJSONを返すAPI」というような認識をされています。そういった定義の中では、本書で解説しているのは REST API ですが、本書ではこれらのデザインについてRESTという言葉は極力使わずに解説を行なっています。
なぜならもともとのRESTという言葉の定義としているものと、本書がいいパーツとして紹介するルールが、必ずしも一致しているとは限らないからです。
（本書の1.6より）
という風に書かれています。なので、REST API という言葉は紹介文にはでてきませんが、REST API について知りたいと思っている人は為になると思います。
目次
- Web APIとは何か
- エンドポイントの設計とリクエストの形式
- レスポンスデータの設計
- HTTPの仕様を最大限利用する
- 設計変更をしやすいWeb APIを作る
- 堅牢なWeb.APIを作る
全6章構成になっています。
本当に2014年発行なの？！
本書は初版が2014年11月19日です。もう5年以上前です。初版しかないです。
この移り変わりの早い界隈で、5年以上前というと、とても古い本に感じてしまいます。
私はiOSエンジニアをメインとしているので、例えば Swift で考えると、同年の2014年に生まれた言語になってしまいます。言語が出た頃と今では破壊的変更もありますし、その頃の本はほとんどが役に立たないものになってしまっているでしょう。
そのくらい年月が経っている本なのに、本書は全然それを感じさせないです。
もちろん進化していることもあると思いますが、APIの基礎を得るにはとても良い本でした。
200ページ程度でまとめられているので、結構薄い本です。
API は誰が設計すべきか
さて。今回本書を読むに至った経緯は、お仕事で必要になったからです。
私はiOSエンジニアをしていて、クライアント側の実装を行なっています。サーバ側のことはサッパリです。
新規画面に取り掛かっているときに、APIの設計をしてからやってみてと言われて、承知しましたと答えながら、うん？ってなりました。APIの設計？それって、サーバ側のことをよく知ってないと無理なんじゃないの？と。
とにかくAPIの設計なんてしたことがなかったので、本書を手にしたわけです。
結果的に、APIの設計はサーバ側の仕事だと決めつけるのは間違っていたと感じました。
まずはエンドポイントの設計で、以下のような記述が出てきます。
ウェブアプリケーションでは、URIがサーバ側のアーキテクチャやディレクトリ構造を反映する必要はまったくありません。Web API においても、URIが反映すべきは機能やデータの構造と意味であり、サーバがどうやって動いているかではないのです。
（本書 2.2.1.5 より）
はえー。ってなりました。
またレスポンスデータに関しても、以下のような記述があります。
繰り返しになりますが、APIは内部で持っているDBのテーブル構造をそのまま反映したものである必要は全くありません。
（本書 3.5より）
そして2章ではスマートフォン向けのアプリケーションとAPIデザインについて、以下のように書かれています。
こうしたケースでは、必要とされるAPIの設計は、必ずしも汎用的という観点からは美しい必要はありません。2014年3月に行われた「API Strategy and Practice」における「Michele Titolo 氏と Paul Wright 氏の講演」においても「1スクリーン 1APIコール、1セーブ 1APIコール」という言葉が出てきており、これはひとつの画面を表示するためにコールするのが1つのAPIですむように合わせたAPIを用意し、何らかのデータをサーバに保存する場合にも1回のコールですむようにそれ向けのAPIを用意するのがよい、ということが述べられています。
（本書の 2.8 より）
こうやって読んでみると、APIを設計するのはサーバサイドだという認識は間違っていたなぁと思いました。
特に広く一般に使用されるAPIではなく非公開APIにおいては、クライアント側がはっきりしているので、欲しい形をより詳しく知っているのはクライアント側でしょう。
結局、双方で議論して決める必要のあるものだったんだなと気づきました。
クライアント側の人もおすすめ！
先ほど話した通り、Web API の設計にはクライアント側の人にも関わりがあるものです。
エンドポイントやレスポンスの設計に限らず、ヘッダの読み方やステータスコードの意味を知っている必要があるはずです。
お恥ずかしながら、ヘッダの読み方だけではなくステータスコードの意味もほとんど知らずにAPIを叩いていました。というよりクライアント側の実装もAPI関連は全然やっていなくて、本当に知識ないんだなって感じでした。
その辺を読めるようになることで、プロジェクトのAPIドキュメントをまともに読めるようになりました。
Web APIに関する最低限の知識が詰まっていますので、APIを設計する方だけでなく、利用する方にもおすすめです。
おわりに
遅読なので3日くらい溶かしてしまったんですが、これは本当に読んでおいてよかったです。何も知らずに設計を始めなくてよかったって本当に思います。
もちろん調べればいくらでも出てくることなのかもしれませんが、こうやってまとまった情報というのはとても価値がありますよね。
一読しただけで設計ができるはずもなく、とても苦戦しています。難しいです。
一画面のレスポンスとエンドポイントを設計する程度なので、ヘッダとかをセキュリティ考えて設計するのは厳しいですね。めっちゃ大変そう。0からAPI作るってなるとそういうことも考えないといけないことを考えると恐ろしい…。
あとはAPIについての知識があることも大切ですが、携わっているプロジェクトについて詳しくないとAPIって作れないなって感じました。そういう意味ではクライアントサイドやサーバサイドという括りではなく、もっとプロジェクト全体が見渡せている人がAPI設計士になって欲しいなぁなんて思いました。
オライリー本はあんまり選んできてなかったけれど、結構いいね。家にあるけど読んだことないリーダブルコードもそのうち読もう。。。
ではでは。
コメント時の注意
「Twitter」「Facebook」「Google+」「WordPress」のいずれかのアカウントをお持ちの方は各アカウントと連携することでコメントできます。 コメントしたことはSNSに流れませんので、アカウントをお持ちの方はこちらの方法でコメントを投稿して下さると嬉しいです。 アカウントをお持ちでない方はメールアドレスで投稿することができます。 初回コメント時は承認後に表示されます。