Web API:The Good Parts

Web API の設計、開発、運用についての解説書。本書では API をどのように設計し運用すればより効果的なのか、ありがちな罠や落とし穴を避けるにはどういう点に気をつけなければいけないのかを明らかにします。ターゲットは、URI にアクセスすると XML や JSON などのデータが返ってくるシンプルなタイプー XML over HTTP 方式や JSON over HTTP 方式ーの API です。

『Web API: The Good Parts』 (水野 貴明 著、オライリー・ジャパン、2014 年 11 月刊) は、URI にアクセスすると JSON や XML のデータが返ってくる形の Web API を、どう設計し運用すれば使いやすく保守しやすくなるかを解説した書籍です。対象は版元の紹介文が言う JSON over HTTP 方式や XML over HTTP 方式の API で、「設計の美しい API は、使いやすい、変更しやすい、頑強である、恥ずかしくない」という考えのもと、ありがちな罠や落とし穴を避けるために何に気をつけるべきかを明らかにする本と説明されています。API を公開する側に立ちながら、エンドポイントの名前やエラーの返し方をその場の判断で決めてきた開発者に向いた一冊です。

全 6 章と付録 2 本、エンドポイント設計から堅牢性まで

構成は 1 章「Web API とは何か」から 6 章「堅牢な Web API を作る」までの全 6 章に、付録 A「Web API を公開する際にできること」と付録 B「Web API チェックリスト」が続きます。1 章は何を API で公開すべきか、REST と Web API の関係、対象となる開発者の数と設計思想を整理し、2 章「エンドポイントの設計とリクエストの形式」は HTTP メソッドとエンドポイントの対応、検索とクエリパラメータ、ログインと OAuth 2.0 を経て、HATEOAS と REST の成熟度 で言うレベル 3 の API までを扱います。3 章「レスポンスデータの設計」はデータフォーマットや JSONP の取り扱い、データの内部構造、エラーの表現を、4 章「HTTP の仕様を最大限利用する」はステータスコードの使い方、キャッシュ、メディアタイプの指定、同一生成元ポリシーとクロスオリジンリソース共有、独自の HTTP ヘッダを取り上げます。5 章「設計変更をしやすい Web API を作る」は API のバージョン管理 とバージョンを変える際の指針、提供の終了、オーケストレーション層を、6 章は通信経路での情報の不正入手、ブラウザからアクセスする API の問題、セキュリティ関係の HTTP ヘッダ、大量アクセスへの対策を扱います。

公開した API が変えにくい理由と、HTTP に乗る設計の効き目

Web API の設計が難しいのは、一度公開すると利用者のコードがその形に依存し、名前やデータ構造、エラーの形を後から変えにくくなる点にあります。社内の関数なら呼び出し元をまとめて直せますが、外部の開発者が使う API ではそれができないため、最初の設計の粗さがそのまま保守の負担として残ります。もう一つの軸は HTTP の仕様との付き合い方です。ステータスコードやキャッシュの指示、メディアタイプといった仕様どおりの手段で意味を伝えれば、クライアントのライブラリやプロキシといった既存の仕組みがそのまま働きます。逆に独自の約束事で包むと、利用者はそのたびに個別の取り決めを読み解く必要が出ます。本書が HTTP の仕様の活用に 1 章を充て、設計変更のしやすさと堅牢さにもそれぞれ 1 章を割いている構成は、使いやすさと変更しやすさ、頑強さという紹介文の軸と対応しています。

2014 年刊の前提と、向いている読者 / 向かない読者

本書は 2014 年時点の技術環境を前提にしています。3 章に JSONP の取り扱いが置かれているのはその表れで、クロスオリジンの通信を CORS で扱うことが一般的になった後の読者は、その節を当時の事情として読むことになります。目次には GraphQL や gRPC といった別の方式の項目は無く、扱う範囲は HTTP と JSON を中心にした API に絞られています。前提として、HTTP のリクエストとレスポンスの基本、JSON の読み書き、何らかのサーバーサイドの開発経験があると理解が早く進みます。一方で、特定のフレームワークでの実装手順を求める人や、HTTP 以外の方式を含めて API の選択肢を比べたい人には目的が合いません。Web 開発の学習全体の中で設計の本をどこに置くかを考えたい場合は、Web 開発本の選び方 を合わせて見ると位置づけがつかみやすくなります。

自社のサービスに API を追加する、あるいはスマートフォンアプリ向けのバックエンドを任されたものの、エンドポイントの切り方やエラーの形に毎回迷っているという人にとって、本書は判断の拠り所を章ごとに確認できる一冊です。付録 B のチェックリストは公開前の見直しにそのまま使えるため、設計を一度通して学んだ後も、手元に置いて元が取れる使い方ができます。