やったこと

現場で役立つシステム設計の原則 8章 読了

学んだこと

アプリケーション間連携

基本はデータのやり取り。
以下が代表的な方法。

• ファイル転送
• データベース共有
• Web API
• メッセージング

■ファイル転送

ファイルをやり取りする両者でフォーマットを決め、フォーマットに従ったファイルをやり取りする方法。

以下の問題点がある。

• ファイルをまとめて転送する設計になりやすく、リアルタイム性に欠ける
• 一度システムを構築してしまうと、ファイル形式の変更が困難

■データベース共有

必要なテーブルやデータ範囲を共有する。

以下の問題がある。

• データベースを直接共有するというセキュリティ上の問題
• テーブルとプログラムが密結合となり、変更が困難に

■Web API

HTTPエンドポイントを設け、エンドポイントを通してデータをやり取りする。
必要な情報のみやり取りでき、様々なシステムと連携可能。

以下の問題点がある。

• 設計の自由度が高い
• 一度公開すると、APIの変更が困難
• 「リクエストを送信してレスポンスを待つ」という同期型の処理方式が、運用面と性能面で制約となる

■メッセージング

キューなどのメッセージング基盤を介してデータをやり取りする。非同期型の通信方式。
アプリケーションを疎結合化でき、並行処理によって大量のメッセージを捌くことができる。

以下の問題点がある。

• メッセージング基盤のための設計・運用技術が必要
• 安定したメッセージング基盤の構築と運用

put と post の違い

どちらもデータ登録用のメソッド。

putは、識別子を使用してデータの登録を行う。
識別子が合致するデータが存在すれば上書きし、存在しなければ新規作成する。

putは以下の理由により、postと比較して結合が密になる。

• putを実行する側で、データソースの識別体系を把握しておく必要がある
• putの応答（≒ステータスコード）を定義する必要がある
  • 応答内容の決め事が増え、結合が密になる

基本は、疎結合となる post を使用する。

postで更新（または削除）を行う

以下のように行う。

1. 更新（または削除）用のURIを構築する
   • https://api.example.com/books/1234/deletion
2. 上記URIに対してPOSTメソッドを実行する

クライアント側からすると、更新（または削除）を依頼するのみという形になる。
更新（または削除）処理は、サーバ側に隠匿する。
これにより、アプリケーション間の結合を疎にする。

良いWeb APIとは何か

アプリケーションの組み立ての多様性を維持しつつ、組み立て側の負担が増えすぎない、必要十分な情報を提供するAPI。

• なんでもできる一つの巨大なAPIは、呼び出すためのパラメータが非常に多く、これらをすべて把握しなければならないため使い勝手が悪い
• 小さすぎるたくさんのWeb APIは、呼び出し側で組み立ての負担が増える

API 開発方法

試しに作ってみて、ニーズを満たすか検証を交えつつ、フィードバックを基に修正/拡張を繰り返す。

■重要なポイント

• Web API用のフレームワークやライブラリを導入
  • Sprint MVCの「REST Controller」など
• APIドキュメントやテスト画面を自動生成するツールを導入
  • 「Swagger UI」 など
• 迅速なフィードバック
• APIの成長サイクルを回す

■APIを複合したサービスの提供

複合サービスを提供する場合、どうしても利用者側の知識が入り込み、密結合化する。
基本、複合サービスは利用者側で構築してもらう。

複合サービスを提供する場合、APIの提供を、以下の二層に分離する。

• 複合サービスを提供する層
• 基本APIを提供する層

ドメインオブジェクトとWeb API

ドメインオブジェクトとWeb API（ぶっちゃけJSON）の相互変換は、以下の理由により不都合が発生しやすい。

• データ構造の不一致
• 関心事の不一致

データ構造の不一致

特に、データ項目が多い場合に発生する問題。

Web API側は、データのみに関心があるため、可能な限り単純な構造が良い。
一方で、ドメインオブジェクトは、業務ロジックを反映した階層構造を持つ。

どちらに寄せるかが大きな課題。

関心事の不一致

API利用者は、ドメインオブジェクトが持つすべての情報を必要とするとは限らない。
ドメインオブジェクトが期待するデータ項目が、すべて送信されるとは限らない。

ずれが小さい場合は、ドメインオブジェクトとJSONのマッピングで対応する。

ずれが大きい場合は、変換用の中間オブジェクトをプレゼンテーション層に実装する。

• POST request (JSON) -> Request オブジェクト -> ドメインオブジェクト
• ドメインオブジェクト -> Response オブジェクト -> POST response (JSON)

変換オブジェクトの用意は必須ではない。
変換オブジェクトは、ドメインオブジェクトに、I/Fやクライアント側の都合（JSON対応など）を持ち込まないために利用する。

複雑な連携

関係者が増えると、Web APIが複雑化する（特に公開API）。
以下をはっきり分けて設計する。

• コアとなる基本API
  • どの利用者にも共通で提供するAPI
• 拡張API
  • 基本APIを組み合わせて提供する複合API
  • どの利用者にも共通で使用できるものを提供する
• 個別対応API
  • 特定の利用者のニーズを満たすAPIの集合

Web APIを育てる

個別のニーズを満たしつつ、他の利用者のニーズとも合致したら共通APIに組み込んでいく。
このように、環境の変化に合わせてWeb APIを育てていくことで、APIの価値を高め続けることができる。

Web APIは進化するからこそ利用され続ける。利用され続けるからこそ、発展できる。