原著 : The Design of Web APIs

著 : Arnaud Lauret

翻訳 / 監修 : 株式会社クイープ

発行年 : 2020 年

Amazon : https://amzn.to/3Y3i7av

本書に寄せて (Kin Lane)

過去 10 年以上、API 設計とは、ほとんどの開発者にとって REST のことだった

本書は、次世代の API ガイダンスの第一波

本書は、API 設計と OpenAPI (以前は Swagger) を考え抜かれた実践的な方法で融合させた初めての API 設計の本

Web API は、現代の 「つながる世界」 の大黒柱とも言えるもの

リモート API、その中でも特に Web API によって、ソフトウェアを作る方法に大変革が起きている

API を設計するにあたって、包括的で正確なゴールリストを作る

ユーザーは誰か？ (例えば管理者もユーザーになる)

ユーザーの目標 (ゴール) に対して、「何を」 「どのように」 実現するかを考える

さらに、それぞれのステップにおける 「入力」 と 「出力」 を考える

入力はどこから得る？ 出力はどう使われる？ ということを考えると、見落としている API のゴールを洗い出せる

上記のゴールリストを作るにあたって、API のゴールキャンバスを活用する

API 設計にプロバイダの視点を入れないようにする

API 設計にも Conway の法則は影響しうる (API 設計は、API を提供している組織のコミュニケーション構造を反映しうる)

内部のデータ構造を露出しないように

ビジネスロジックや複数のシステムが連携する場合のアーキテクチャなどの影響も受けないように

組織構造の影響を受けないように

REST、HTTP、REST API

REST という API スタイル以上に、REST アーキテクチャスタイルという土台が大事

OpenAPI Specification (OAS) はよく知られている REST API 記述フォーマット

API にはユーザビリティも重要

単純明快な表現 : 明確な名前、使いやすいデータ型とデータフォーマット

単純明快なインタラクション

エラーフィードバックを洗い出す

不正な形式のリクエストエラー (malformed request error)

機能的エラー (functional error)

サーバーエラー

情報的価値のある成功およびエラーのフィードバック

包括的なエラーフィードバック : エラーが複数あるならばまとめてエラーを返す

単純明快なフロー

4 つのレベルの一貫性 : API 内部、組織・企業・チームの API にまたがる一貫性、API の問題領域での一貫性、外の世界との一貫性

標準に従う

例

「再生」 と 「一時停止」 の記号は ISO 7000 で定義されている

通貨の分類は ISO 4217

日付と時刻は ISO 8601

HTTP の標準に従うという意味でも

適応可能な API

さまざまなフォーマット

JSON、CSV、PDF などの様々なフォーマット

コンテンツネゴシエーションを使える

国際化と地域化

ISO 639 に言語コードが規定されているが、アメリカ英語とイギリス英語の違いなどはない

RFC 5646 では言語タグが定義されている (ISO 639 の言語コードと、ISO 3166 の国コードを採用)

HTTP では Accept-Language と Content-Language

フィルタリング、ページング、ソート

メタデータの提供

HAL、Collection+JSON、JSON API、JSON-LD、Hydra、Siren など

セキュア・バイ・デザイン (secure by design) である必要

API の互換性

ネットワークの制約

など

『OAuth 2 in Action』 や 『API Security in Action』 が詳しい

RFC 6749 の OAuth 2.0 の認可フレームワークを紹介 (これが唯一の選択肢ではないがよく利用される)

OWASP (Open Web Application Security Project)

エンドポイントをスコープで分類して、スコープごとのアクセス制御を行う

OpenAPI Specification 3.0 はスコープをサポートする

センシティブなデータの扱いにも気を付ける

法規制などもある

銀行のクレジット / デビットカードの扱い : PCI DSS (Payment Card Industry Data Security Standard)

アメリカのヘルスケアプロバイダの規制 : HIPAA (Health Insurance Portability and Accountability Regulation)

EU の GDPR (General Data Protection Regulation)

破壊的変更 (互換性のない変更) に注意

ネットワークの通信効率は重要

API をレイヤ化する

Backend For Frontend (BFF)

設計はコンテキストの影響を受ける (人々が何に慣れているのか、など)

QWERTY の話

ISO 20022 規格

ポーリングではなくコンシューマにイベントを通知

Web フック (リバース API)

Server-Sent Events (SSE)

道具の法則 (ハンマーの法則やマズローの法則とも) と呼ばれる認知バイアス

Web API の基本である同期型のリクエスト / レスポンス + REST + HTTP/1.1 + JSON を常に使いたくなるかもしれない

他の選択肢もある

REST、gRPC、GraphQL

データフォーマットとして、protocol buffers も

同期型のリクエスト / レスポンスだけでなく、イベント通知も

Web フック、WebSub

RabbitMQ などのメッセージングシステム

信頼性の低いネットワークやスリーピングデイバス ( スリーピングデバイスの誤植？) を使った双方向通信には MQTP (Message Queuing Telemetry Protocol)

大量のイベントフローの処理には Kafka Streams など

利用者向けの説明書だけでなく、実装者向けの説明書も必要 (あるいは設計者が実装に参加する)

標準化されている規格が多いが、全部を知っている事は難しい

例えば電話番号については ITU-T E.164

判断力と検索エンジンの力が重要

#書籍 #文献