Web API の設計

さまざまな Web を構成する重要な要素「API」
使いやすく拡張性に富み、堅牢な API の設計指南書

【本書の内容】
本書は
Arnaud Lauret, "The Design of Web APIs",
Manning Publications, 2019
の邦訳版です。

SNS はもちろん動画システムや決済システムなど、いまや API (アプリケーション・プログラミング・インターフェイス) を使用しない Web 上のシステムはありません。
データを簡便にリクエストでき、使いやすいデータを返す。そういう API が求められています。
とはいえ、データをリクエストしてくるのは一か所ではありません。カスタマーがいてコンシューマーがいてデベロッパーがいて、そしてそれぞれがそれぞれの都合に合わせた使えるデータを要求してきます。

本書はこういった複雑な要望に対して、可能な限り応ええる柔軟性を備え、堅牢でシンプルな API を作る方策を示します。
コマース系のサイトをベースに、データの配置方法や拡張性を維持し続ける方法などを、実装ありきではないスタイルで、API のすべてを語り尽くしています。また、メンテナンス性や、より多くのユーザーを獲得するためのドキュメントの記述・完備方法なども詳解します。
突貫で作りがちな API を、その使い勝手にフォーカスしながら正しく作り込んでいくための視点と姿勢を体得できる一冊です。

本書は、著者 Arnaud Lauret の長年の API 設計経験を利用し、
要件を収集する方法、ビジネス目標と技術目標のバランスを取る方法、
および消費者第一の考え方を採用する方法について、仔細に検討し、
より使いやすく可用性に富み、拡張性と堅牢性をもつ API 構築への道を詳解してくれます。

【本書のポイント】

・使うだけではなく使える API を理解できる

・API 設計の勘所がつかめるようになる

・実世界におけるユーザー指向 API を学べる

・手書き風の概念図がかわいい

【読者が得られること】

・API の成り立ち

・使いやすい API の作り方

・可用性・発展性のある API の設計方法

Web API を、作る側の内部の都合ではなく、呼び出す側の開発者が迷わずに使える形へ設計するための考え方をまとめたのが『Web API の設計』です。原書は Arnaud Lauret の The Design of Web APIs (Manning Publications、2019 年) で、日本語版は株式会社クイープの翻訳と監修により、翔泳社の Programmer's SELECTION の一冊として 2020 年 8 月に刊行されました。副題は「ユーザブルでセキュア、効率的で進化可能な Web API をデザインする際に知っておくべきこと」です。版元は本書を使いやすく拡張性に富む堅牢な API の設計指南書と位置づけ、コマース系のサイトを題材に、実装ありきではないスタイルで設計の判断を解説すると案内しています。

3 部 13 章の構成、API デザインの基礎から成長まで

本文は 3 部 13 章です。第 1 部「API デザインの基礎」は第 1 章「API デザインとは何か」から始まり、第 2 章「ユーザーを意識した API を設計する」で API のゴールを洗い出す手順と、設計時にプロバイダーの視点を回避することを扱います。第 3 章「プログラミングインターフェイスを設計する」は洗い出したゴールを REST API に置き換えてデータを設計する章で、第 4 章「API 記述フォーマットを使って API を記述する」は OAS と JSON Schema による記述に充てられています。第 2 部「ユーザブルな API の設計」は第 5 章から第 7 章までの 3 章で、表現、インタラクション、フローの単純さと、一貫性、適応性、発見可能性、API の整理とサイジングを取り上げます。第 3 部「コンテキストに応じた API デザイン」は第 8 章「セキュアな API を設計する」から第 13 章「API を成長させる」までの 6 章で、アクセス制御、進化とバージョニング、ネットワーク効率、API スタイルの選び方、文書化、設計ガイドラインとレビューへと範囲を広げます。どの章も最後の節がまとめです。

呼び出す側から考える設計と、仕様を記述する意味

API の設計が難しいのは、作る側が知っているデータベースの構造や処理の順序が、そのまま外へ漏れやすいからです。テーブルを URL へ写しただけの API は早く作れますが、呼び出す側は内部の事情を理解しないと目的の操作にたどり着けません。HTTP のメソッドとリソースを表す URL の組み合わせで操作を表す REST API は、Web API の設計で共通の語彙として使われる様式で、本書は第 3 章でこの様式へゴールを置き換える段取りを示します。また、仕様を機械が読める形で書き出しておくと、文書やモック、クライアントのコードを同じ記述から生成でき、設計の段階で関係者と合意を取りやすくなります。本書が OAS と表記するのは、その代表的な記述形式である OpenAPI の仕様のことです。

一度公開した API には利用者のコードが依存するため、項目名を変えるだけでも呼び出す側を壊しかねません。破壊的変更を管理する戦略 は、公開した後で慌てて考えるより、設計の段階で拡張の余地を残しておく方が安く済みます。第 9 章は進化とバージョニングに加えて拡張性を念頭に置いた設計を扱い、第 12 章は進化と終了の文書化までを取り上げます。

API 設計の判断基準がほしい開発者に向く一冊

本書の議論は特定のプログラミング言語やフレームワークのコードを前提にしていないため、API を公開するバックエンドの開発者だけでなく、仕様を決める立場の人や設計レビューに関わる人も読み進められます。第 13 章には API の設計ガイドラインの作成とレビューの節があり、チームで設計の基準を揃えたい場合の手がかりになります。逆に、特定のフレームワークで API サーバーを実装するコードの書き方を学びたい場合は、目次にその種の章は無いので、実装の入門書と組み合わせる必要があります。版元は手書き風の概念図も本書のポイントに挙げています。

これまで動けば良いという基準で API を作ってきて、エンドポイントの切り方や項目の名付けに毎回迷っている人、あるいは公開した API の変更で利用者を困らせた経験がある人にとって、ゴールの洗い出しから文書化と成長までを一続きで示す本書は、設計の判断に理由を持たせるための確かな土台になります。まず第 1 部の 4 章を通して読み、手元の API を一つ当てはめてみることから始めてください。