Zenn
🔖

「マスタリングAPIアーキテクチャ」を読んだ

2025/01/06に公開
books
tech

APIアーキテクチャ

本書では、APIアーキテクチャのコンテキストを共有するためのC4モデルとアーキテクチャの決定事項を記録するためのADRを使って、アーキテクチャの進化の決定のプロセスが紹介されている。
意思決定の多くの状況においての答えは「場合による」ため、コンテキストや文脈なしに「場合による」と言うのではなく、「何に依拠するのか?」を説明してアーキテクチャを進化させる決断をする必要がある。
技術的な実装の詳細には立ち入らないが、各アーキテクチャの決定のポイントでADRガイドラインが提示されるため、アーキテクチャとして決定をしていく場面をケーススタディを通して学ぶことができる。

APIの定義とテスト

RESTAPIの構築にあたり、RESTAPIには基本的なルールがあるが、実装や設計は開発者に委ねられているためAPI標準 https://github.com/masteringapi/rest-api-standards を参考に実装設計を検討したい。

公開されているAPI標準一覧のGithubページhttps://github.com/masteringapi/rest-api-standards

Owner/Steward Link
Adidas https://github.com/adidas/api-guidelines/tree/master/rest-api-guidelines
Atlassian https://developer.atlassian.com/server/framework/atlassian-sdk/atlassian-rest-api-design-guidelines-version-1/
Google https://cloud.google.com/apis/design
Heroku (extract) https://github.com/interagent/http-api-design
Microsoft https://github.com/microsoft/api-guidelines
The White House https://github.com/WhiteHouse/api-standards

APIトラフィック

APIトラフィックは、エンドユーザーからシステムに流入する外部トラフィックとサービス内部で発生しシステムを横断する内部トラフィックがある。
APIゲートウェイを使って外部トラフィックを管理し、サービスメッシュを利用して内部トラフィックを管理する。

「なぜAPIゲートウェイを使うのか？」

- フロントエンドとバックエンドの間でファサード/アダプタを利用することで疎結合を実現します。
- バックエンドサービスを集約/変換することで簡素化します。
- 脅威の検知・緩和、APIを過剰利用や悪用から保護します
- APIがどのように利用されているかを理解します。
- APIライフサイクル管理でAPIを製品として管理します。
- アカウント管理、課金、決済を利用しAPIをマネタイズします。

ここでさらに興味深かったのは、APIゲートウェイの近現代史が紹介されている。

1990年代以降: ハードウェアロードバランサ

各サイトにアクセスするユーザー数が増えるにつれ、基盤となるWebサーバに負荷がかかるようになりました。そのため、負荷の分散をサポートし、かつ耐障害を備えたシステムの設計が求められました

2000年代前半以降: ソフトウェアロードバランサ

Webサイトの高可用性と拡張可用性に対する要求が高まり、初期のハードウェアロードバランサの費用と柔軟性の低さが成約になり始めた。2002年にNGINXが発売され、この機能を実現できるソフトウェアロードバランサや汎用プロキシが登場

2000年代半ば: アプリケーションデリバリコントローラー

インターネットに接続可能な携帯電話の登場。Ajax技術がブラウザに採用され、「Web2.0」が登場
Webサーバーとロードバランサは、より多くの負荷を処理するだけでなく、暗号化通信、データペイロード、異なる優先度のリクエストをサポートする必要が発生。
アプリケーションデリバリコントローラーは、圧縮、キャッシング、接続の多重化、通信シェーピング、SSLオフロードをサポート

2010年代前半: 第一世代のAPIゲートウェイ

APIエコノミーとそれに関連する技術が出現。Twilio、Google Ads API、Stripe。
「製品としてのAPI管理」を可能にする基礎ができた

2015年以降:第二世代のAPIゲートウェイ

認証、テスト、レート制限、負荷分散、オブザーバビリティなど、多くの機能王な課題を単一のエッジコンポーネントに統合。

「なぜサービスメッシュを使うのか？」

- サービスルーティング、信頼性、 トラフィック管理の細かい制御可能にする
- サービス間呼び出しの可視性を向上させる
- トランスポートの暗号化、認証認可などを含む実践をする
- 他言語にわたる機能横断的な通信要件をサポートする
- 外部トラフィックとサービス間のトラフィック管理を分離する

サービスメッシュの実装は、クラスタやデータセンタ内でのサービス間、あるいは内部トラフィックを処理するために最適化。
通信の送信側は通常、既知の内部サービスであり、ユーザーのデバイスや、アプリケーションの外部で実行されないことが一般的。

将来に向けての準備

将来、APIアーキテクチャに与える影響のあるトピック

  • 非同期通信(AsyncCommunication)
    AsyncAPIは、非同期APIの仕様を提供する。イベント駆動駆動アーキテクチャの人気。
  • HTTP/3
    QUICを採用しており、UDPをもとにしたトランスポートレイヤプロトコル
    QUICへの切り替えは、HTTP/2の主要な問題である「ヘッドオブラインブロッキング」を解消することを目的
  • プラットフォームベースのメッシュ
    サービスメッシュの標準、ServiceMeshInterface(SMI)

次のアクション

  • 基本を絶え間なく磨く
    学習したいスキルの基本を常に見直すことが重要。「古いものが新しい」

まとめ

アーキテクチャは目標を決定し、システムを進化させるまえに、変更の背後にある動機を明確にするべき。目標を整理し、チームや組織と明確にコミュニケーションをすべき。
その段階で検討するべきADRガイドラインが提供され、ケーススタディとともに検討プロセスが紹介されている。

以下は本書で気になった箇所を抜粋する。

イントロダクション

APIは大まかに言えば、API呼び出しがプロセス内(in-process)か、プロセス外(out-of-process)か、という2種類の一般的なカテゴリに分類することができます。ここで言うプロセスとは、オペレーティングシステム(OS)のプロセスを意味します。例えば、あるクラスから別のクラスへのJavaメソッドの呼び出しは、呼び出しが行われたプロセスと同じプロセスで処理されるため、プロセス内のAPI呼び出しとなります。.NETアプリケーションがHTTPライブラリを利用して外部のRESTAPIを呼び出す場合は、呼び出し下のプロセスとは異なる外部プロセスで処理されるため、プロセス外のAPI呼び出しとなります。

0.4 C4ダイアグラムの利用

C4モデルは、ソフトウェアアーキテクトや開発者がソフトウェアをどのように考え、構築を行うか、抽象化して、ソフトウェアアーキテクトを図示するアプローチ。

0.4.1 C4コンテキスト図

この図の目的は、技術的な利用者と非技術的な利用者の両方に対し、コンテキスト(文脈)を設定することです。
多くのアーキテクチャに関する会話は、低レイヤの詳細へ行く傾向があり、概論レベル(高レイヤ)におけるやり取りのコンテキスト説明を見落としがちです。

0.4.2 C4コンテナ図

コンテナ図は、アーキテクチャの主要要素の技術的役割を説明。C4におけるコンテナとは、「システム全体が動作するために必要なもの」と定義。

0.4.3 C4コンポーネント図

C4コンポーネント図で、これは各コンテナ内の役割と責任、内部トラフィックを定義するのに役立つ。

0.5.2 APIを極める:ADRガイドライン

意思決定を行う際に問うべき重要な質問を収集するのに役立つADRガイドラインを提供。
APIアーキテクチャに関する意思決定は本当に難しいことが多く、多くの状況に置いて答えは「場合による」、です。ADRガイドラインは、コンテキストや文脈なしに「場合による」と言うのではなく、「何に依拠するのか？」を説明

1.5 REST APIの標準化と構造化

REST APIには基本的なルールがありますが、ほとんどの場合、実装や設計は開発者に委ねられています。例えば、「エラーを伝えるために最適な方法はなにか？」「ページネーションはどのように実装すればいいのか?」

Discussion