SOAPless
無料で始める
ブログへ戻る
soaplegacy-modernizationvendor-apisintegrationsoap-to-rest

接続先の SOAP サービスを変更できないときの実践ガイド

SOAPless Team14 min read

SOAP-to-REST 層を導入する最も強い理由は「REST の方が好きだから」ではありません。

接続先の SOAP サービスは、こちらでは変えられない。

この制約がある瞬間、facade は好みの問題からインフラの問題に変わります。XML envelope の手組み、認証ロジックの散在、ドキュメント化されていない SOAP fault。これらの複雑さを各チームが個別に吸収しているうちに、気がつけば 3 チームが同じ WS-Security ヘッダーのデバッグをしている――そういう状況が生まれます。

この記事では、接続先を変えられない 4 つの典型シナリオ、チームが詰まるパターン、そして managed な境界層を置くべきかどうかの判断基準を整理します。

シナリオ 1: ベンダー API（PDF 仕様書のみ、交渉不可）

国内外の ERP ベンダーや決済プラットフォーム、保険基幹システムなどは、SOAP endpoint を公開していても、仕様書は PDF 1 本だけということが珍しくありません。サンドボックス環境がないケースも多く、契約変更の交渉チャネルは事実上存在しません。

日本市場で特に多いのは、国内 ERP ベンダー（SAP、Oracle、OBIC など）の連携 API です。WSDL は提供されるものの、PDF 仕様書と実際のレスポンスが微妙にずれていることがあり、実行時に初めて差異に気づきます。

つらいポイント:

  • 仕様の交渉ができない。 ベンダーが出したものがすべてです。WSDL に記載されていないオプショナルヘッダーが本番では必須だった、という話は珍しくありません。
  • PDF 仕様書がドリフトする。 ドキュメントには getOrderStatus が StatusCode を返すと書いてあるのに、実際のレスポンスは OrderStatusCode。XML parser が静かに失敗します。
  • バージョニングが不透明。 ベンダーは自社のスケジュールでサービスを更新します。breaking change に気づくのは changelog ではなく、本番の 500 エラーからです。

シナリオ 2: 委託先・パートナーの SOAP サービス

SOAP サービスの運用が委託先やパートナー企業にある場合、力学が変わります。パートナーには納品義務がありますが、優先度はこちらとは一致しません。

日本の SI 業界では、大規模システムの一部を協力会社が開発・運用するケースが多く、WSDL の変更には正式な変更依頼書、影響調査、見積もりが必要になることがあります。フィールド名を 1 つ変えるだけでも、そのプロセスを回す必要があります。

よくある摩擦:

  • 納期の非対称性。 こちらは隔週リリース。パートナーは四半期リリース。2 日で直せるバグがパートナーのバックログで数か月待ちになります。
  • 契約上の硬直性。 WSDL contract の変更には正式な変更要求、法務レビュー、追加費用が発生する場合があります。
  • 可視性の欠如。 パートナーのログ、デプロイスケジュール、エラー監視にはアクセスできません。サービスが劣化しても、こちらはブラインドでデバッグすることになります。

シナリオ 3: 別部門が管理する社内レガシーシステム

意外に多いのがこのパターンです。SOAP サービスは自社内にあるのに、実質的に外部システムと変わらない状況です。

典型的な例: 経理部門が 2012 年にデプロイした SOAP ベースの請求書サービス。問題なく動いていて、毎月数百万件のトランザクションを処理しています。構築した当時のエンジニアは異動済み。現在の運用チームの KPI は稼働率であって、開発者体験ではありません。

日本の大企業では、この構図が特に顕著です。基幹システムは情報システム部門が管理し、事業部門の開発チームがその API を利用する。しかし予算も承認フローも別系統で、仕様変更の優先度が根本的に噛み合いません。

なぜ厄介か:

  • 優先度ギャップ。 こちらのチームは JSON レスポンスがほしい。向こうのチームは変更要求ゼロを維持したい。どちらもそれぞれのインセンティブ構造の中では合理的です。
  • 同じ組織、別のガバナンス。 同じ会社の中にいるのに、予算もロードマップも承認チェーンも異なります。
  • 知識の減衰。 元の WSDL を設計したエンジニアは数年前に退職しています。正しい呼び出し方を知っているのは 1 人だけ、という状況がありがちです。

シナリオ 4: 行政・公共系エンドポイント

行政系の SOAP サービスは最も制約が強いカテゴリです。仕様はプロダクト判断ではなく法令によって定義されており、変更はスプリントサイクルではなく法改正のタイムラインで起こります。

日本では e-Gov（電子政府）の API、地方自治体の連携システム、国税庁の申告系 API などが該当します。WSDL がインターフェースのすべてであり、REST の代替は用意されていません。機能リクエストのプロセスも存在しません。

特徴的な点:

  • 法的制約。 XML スキーマが法令で規定されている場合があります。シンプルな構造の方が合理的でも、公開標準に準拠する必要があります。
  • 適合性テスト。 一部の行政系エンドポイントでは、本番トラフィックを送る前に適合性試験に合格する必要があります。
  • 変更頻度の低さ。 スキーマ変更は 2〜3 年に一度程度で、6 か月の移行期間が設けられることが一般的です。

共通パターン: なぜチームが詰まるのか

4 つのシナリオに共通する問題は同じです。接続先が変わらないとき、複雑さは消えるのではなく下流に移動します。

利用側の各チームが独立して以下を繰り返します:

  1. WSDL を読み、どの binding を使うか推測する
  2. XML envelope を手組みするか、脆い codegen で生成する
  3. 認証（Basic Auth、WS-Security、クライアント証明書）をゼロから実装する
  4. ドキュメント化されていないエラー形式に対応する fault ハンドリングを書く
  5. エンドポイント固有のリトライ・タイムアウトロジックを構築する

これが 2 チームなら面倒で済みます。5 チームになると保守の危機です。上流の小さな変更が、共通の連携コードを持たない複数のリポジトリで並行デバッグを引き起こします。

また、SOAP の知識が散在すると属人化リスクも高まります。ベンダーの WS-Security 設定を理解している唯一のエンジニアが退職すると、そのコピーに依存していたすべてのチームが影響を受けます。

解決策: managed な境界層

接続先が動かないとき、アーキテクチャとして正しい対応は、固定された SOAP サービスとそれ以外のすべてとの間に、管理された境界を 1 つ置くことです。

この境界層が担うのは:

  • XML 変換。 下流のチームは JSON で送受信し、境界層が envelope の構築とレスポンスのパースを担当します。
  • 認証の一元管理。 クレデンシャル、証明書、セキュリティヘッダーの設定は 1 か所で完結します。
  • Fault の正規化。 SOAP fault を一貫性のある型付きエラーレスポンスに変換し、下流のコードが XML パースなしでハンドリングできるようにします。
  • 契約の安定化。 境界層は OpenAPI 仕様を公開します。上流の WSDL が変わっても、境界層が差分を吸収し、利用側には安定したインターフェースを提示します。

判断基準: 一時スクリプト vs 本番プロキシ

すべての SOAP 連携に managed な層が必要なわけではありません。実務的な判断基準は以下の通りです。

一時スクリプトで十分なケース:

  • 一回きりのデータ移行
  • 担当エンジニアが 1 人
  • 単一環境で実行
  • 1 四半期以内に廃止予定

本番プロキシが妥当なケース:

  • 複数チーム・複数サービスが同じ SOAP エンドポイントを利用する
  • 本番で長期間稼働する連携である
  • 環境ごとに認証設定が異なる（開発、ステージング、本番）
  • 上流の契約が外部管理で、予告なく変わる可能性がある
  • 可観測性が必要: 呼び出し回数、エラー率、レイテンシ

「本番プロキシ」の条件が 2 つ以上当てはまるなら、managed な層への投資は最初の上流変更イベントで回収できます。

SOAPless による解決

SOAPless はまさにこの状況――利用しなければならないが変更できない SOAP サービス――に向けて設計されています。

ワークフローはシンプルです:

  1. WSDL を登録する。 SOAPless のダッシュボードに WSDL URL を貼り付けます。SOAPless がサービス定義をパースし、各 operation に対応する REST エンドポイントを自動生成します。

  2. 認証を 1 か所で設定する。 Basic Auth、WS-Security、カスタム SOAP ヘッダーなど、上流が要求する認証方式を 1 か所で設定します。クレデンシャルは AES-256-GCM で暗号化され、ログには残りません。

  3. REST で呼び出す。 下流のチームは標準的な HTTP で JSON を送信します:

curl -X POST https://proxy.soapless.com/api/v1/your-service/GetInvoice \
  -H "X-API-Key: sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "INV-2025-0042",
    "includeLineItems": true
  }'

レスポンスは JSON で返ります:

{
  "invoice": {
    "id": "INV-2025-0042",
    "status": "paid",
    "total": 84200,
    "currency": "JPY",
    "lineItems": [
      { "description": "年間ライセンス", "amount": 84200 }
    ]
  }
}

XML の構築もデバッグも不要。WS-Security トークンの管理もアプリケーションコードには現れません。

  1. OpenAPI 仕様を共有する。 SOAPless は WSDL から OpenAPI 定義を自動生成します。下流のチームにはこれを渡すだけで、背後に SOAP があることを意識せずにモダンな API 契約に対して連携できます。

まとめ

最も難しい SOAP 連携は、技術的に複雑なのではなく、組織的に制約されています。接続先は変えられない。変えられるのは、その複雑さを自分たちのシステムにどこまで浸透させるかだけです。

managed な境界層を置くことで――自前で構築するにせよ SOAPless のようなサービスを使うにせよ――組織的な制約をアーキテクチャ上の判断に変換できます。SOAP サービスは凍結されたまま。チームは前に進めます。

ブログへ戻る