政府系や公共系の SOAP 連携は、「普通の API 連携」と同じ感覚で入ると事故りやすいです。
接続先のシステムは、たいてい次のような性格を持っています。
- こちらから変えられない
- ドキュメント量は多いのに、実装上の勘所は書かれていない
- 別組織が運用している
- SOAP / XML の古い前提が強い
つまり、お金が溶ける失敗は実装より前に起きます。
1. 何を変えられて、何を変えられないのかを最初に切る
最初に確認したいのはここです。
- 接続先 URL の所有者は誰か
- スキーマや仕様の変更依頼が可能か
- テスト環境はあるか
- WSDL は予告なく差し替わるか
もし「こちらでは何も変えられない」に近いなら、設計の前提として接続先の仕様を固定点に置くべきです。
2. SOAP のバージョンを思い込みで決めない
PDF の概要だけで判断しない方が安全です。
SOAP 1.1 と 1.2 では、envelope namespace も HTTP の流儀も違います。SOAP 1.1 は text/xml と SOAPAction を使うことが多く、SOAP 1.2 は application/soap+xml です。ここを取り違えると、数日単位で違う層をデバッグすることになります。
3. WSDL の port / binding を最初に全部見る
公共系システムでは、binding や service port が複数あることがあります。
先に知っておきたいのは次です。
- 本番で実際に使う binding はどれか
- 接続先 URL はどれが正なのか
- テスト環境と本番で仕様が同じか
- 読み取り系の操作を扱いやすく整理できる余地があるか
これを各チームが個別解釈すると、あとで簡単にズレます。
4. 認証方式は「認証あり」ではなく形まで確定する
「認証が必要です」だけでは情報になりません。
必要なのは、次のどれなのかです。
- HTTP Basic Auth
- client certificate
- WS-Security の
UsernameToken - IP allowlist
- ネットワーク前提の信頼境界
ここが曖昧なまま実装に入ると、当然実装も曖昧になります。
5. 正常系の生リクエスト / 生レスポンスを 1 組確保する
実務ではこれがかなり重要です。
欲しいのは、次を含んだ「通ることが分かっている1本」です。
- 生の HTTP header
- XML envelope
- namespace prefix
- operation wrapper
これがあると、以後は生成されたリクエストをそのサンプルと比較できます。
6. XML の複雑さをどこに閉じ込めるか決める
ここが保守性を決めます。
もし答えが、
利用側の各チームや各スクリプトがそれぞれ XML を組み立てる
なら、結末はだいたい見えています。
現実的なのは次です。
- SOAP envelope の生成を1か所に寄せる
- 認証処理を1か所に寄せる
- ログとテスト導線を1か所に寄せる
- 利用側にはもっと単純な契約を渡す
共通ライブラリでも中継 API でも構いません。大事なのは、XML の壊れやすさを散らさないことです。
7. エラーはきれいに返ってこない前提で組む
公共系 SOAP は、失敗時の挙動が整っていないことも多いです。
想定しておきたいのは次です。
- 雑な
SoapException - 情報量の少ない fault
- 実際は timeout なのに XML parse error のように見えるケース
- 環境ごとの証明書やネットワーク差分
なので、監視や切り分けの導線は後付けではなく最初から計画に入れた方がいいです。
8. 最初のスコープは思っているより小さく切る
最初から契約全体を触らない方が安全です。
まずは次くらいで十分です。
- オペレーションを 1 つ
- 認証方式を1つ
- 環境を1つ
- 検証済みのリクエスト形を 1 つ
そこが通ってから広げる方が、結局早いです。
最後に
政府系・公共系 SOAP 連携で勝ちやすいのは、接続先をねじ伏せることではありません。
自分たちの側で、その複雑さを理解しないといけない場所を減らすことです。