歴史的に見て、システム間のインターフェースの記述はアーキテクトやインテグレーターの専有物であり、しばしばデータ構造を含む電子メールのやり取りにまで収束しました。SOAの時代、特にマイクロサービスアーキテクチャの時代において、システムアナリストの役割は統合契約の形式化および維持において急激に増加しました。
APIインターフェースの誤った、または不完全、古くなった記述は、サービスの互換性の欠如、バグの増加、システム全体の正常な動作を妨げる変更の不可能性の原因となります。マルチサービスプロジェクトでは、統合ポイントの数は数十または数百に達します。
システムアナリストは現代的な実践を適用します：
重要な要素は、契約の適切なバージョニングと変更のトレースの維持、及び相互作用の検証のためのテストケースの統合です。
主な特徴：
アナリストはAPIに関する要件を顧客や内部開発者からのみ収集すべきですか？
いいえ、すべての統合チームを巻き込み、外部パートナーの要件を考慮することが重要で、ギャップや互換性の問題を避けることができます。
システムの提出段階でのみAPIを文書化できますか？
いいえ、APIの仕様は実装前に形成され、合意されるべきで、さもなければ、各ステージで後方互換性が損なわれます。
OpenAPI仕様は、すべての交換ケースに対して十分な文書なのでしょうか？
いいえ、OpenAPIは構造を記述しますが、相互作用のシナリオ（たとえば、呼び出しの順序、イベントの順序、ビジネスエラー）をアナリストはユーザー文書に詳細に記述する必要があります。
ネガティブケース：物流システムが外部の運送業者と統合されました。契約は「言葉だけ」で記述されました。変更が出た後、大規模な統合失敗が発生し、遅延が生じました。
利点：
欠点：
ポジティブケース：アナリストはエラー／成功シナリオの例を含むOpenAPIを作成し、バージョン管理を調整し、すべてのチームからフィードバックを集めました。
利点：
欠点：