マーベリックスのテックブログPublicationへの投稿
🧴

SOAP API入門: 「データ形式の違い」で理解してみよう編

えんどう
に公開
rest
XML
soap
tech

はじめに

普段RESTで開発を行っていますが、お客様の要望により、一部機能をSOAPで提供できないかという相談を受けたことがあります。

私もそうでしたが、そもそもSOAP自体聞きなれない方が多いのではないでしょうか？
私たちが普段Web開発で目にしているのはおおよそがREST APIと呼ばれるものです。

正直、「SOAP？古い技術じゃん」「XML？タグが多くて面倒そう」というネガティブなイメージがある方も多いかもしれません。いざ調べてみても、WSDLだのEnvelopeだの、専門用語の壁に阻まれて最初はよくわかりませんでした。

ですが下記のような捉え方で、自分はだいぶ理解しやすくなりました。

もちろんRESTはJSON以外も扱うことができますが、おおよそはJSONでしょう。
比べてSOAPはXMLのみです。ここが肝。

タグベースでデータをやり取りすることで、XMLを見ただけでこのデータが何者かを判別できるというわけです。結論から言うとこの理解が個人的に一番しっくりきます。

では具体的なデータの違いを見てみましょう。

JSON と XML を比較してみよう

SOAPのデータ形式であるXMLを、普段使い慣れているJSONと比較してみましょう。
例えば、IDや名前を持ったユーザー情報を表現する場合、以下のようになります。

🔹 JSON形式

{
  "user_id": "U001",
  "user_name": "Taro Yamada",
  "email_address": "taro@example.com"
}

🔹 XML形式

<UserData>
  <user_id>U001</user_id>
  <user_name>Taro Yamada</user_name>
  <email_address>taro@example.com</email_address>
</UserData>

このように、JSONにおける"キー": "値"のペアが、XMLでは<タグ>値</タグ>という構造に変わっています。

JSON形式のデータは、まあおそらくユーザーのデータだよね、と読み取れます。
一方でXML形式のデータは、このデータがユーザー情報であることを「UserData」から明確に読み取れます。

今度はもう少し踏み込んだデータを見てみましょう。

🔹 JSON形式

{
  "user_id": "U001",
  "user_name": "Taro Yamada",
  "email_address": "taro@example.com"
}

🔹 XML形式

<ns:getUserDataResponse xmlns:ns="sample-service">
    <return>
        <UserData>
            <user_id>U001</user_id>
            <user_name>Taro Yamada</user_name>
            <email_address>taro@example.com</email_address>
        </UserData>
    </return>
</ns:getUserDataResponse>

JSONの方は先ほどと変わりません。データ自体から読み取れるのは、なんらかのAPIでGETしたユーザーデータの結果なのかな、くらいです。
一方でXMLは何やらタグが増えています。一個ずつみていきましょう。

一番最初のタグ、こちらはサービス名と使われたAPIメソッドが読み取れます。
このタグを意訳すると「sample-serviceのgetUserDataっていうAPIのレスポンス結果だよ」となります。

「return」は「ここから返却値が始まるよ」の意です。
そして上記でも出てきた「UserData」が入っています。

結果的にこのデータの受け取り側は、
「このデータはsample-serviceのgetUserDataっていうAPIのレスポンス結果でUserDataが返却されている」ということが理解できます。

SOAPでは、このXMLのタグ自体がデータの構造と意味（スキーマ）を厳密に定義しているため、受け取り側はデータが壊れていないか、期待した形式であるかを確実に検証できると言うわけです。

こうした理由が、SOAPが金融や医療など、
データの信頼性が重要な分野で使われ続ける理由に繋がります。

つまり、「厳格にやり取りするためにXML使おうぜ」がSOAP APIの本質です。

データ形式以外の観点から見る違い

「JSONがXMLに変わっただけ」という理解はSOAPへの入り口としてわかりやすいと思ったのですが、もちろん厳密に言うと正確な表現ではありません。ですので一般的な内容を少しだけ解説です。

RESTとSOAPを「通信のあり方」という観点から比較すると決定的な違いがあります。

比較項目 RESTful API SOAP API
分類 アーキテクチャスタイル プロトコル（通信規約）
通信形式 HTTPメソッド（GET, POST, PUT, DELETE）に依存 XMLベースのメッセージ（SOAP Envelope）を送信
データ形式 JSONが主流（XMLも可能） XMLのみ
規約 自由度が高く、設計者の裁量が大きい WSDLという厳格な設計書に基づく
トランスポート ほぼHTTP/HTTPSのみ HTTP/HTTPS、SMTP、TCPなど多様なプロトコルを利用可能

RESTは「リソース」を「HTTPメソッド」で操作するという設計スタイルです。一方、SOAPはメッセージの形式から通信方法までを厳密に定めた「プロトコル（規約）」です。

SOAPは、データをXMLで包み込み（Envelope）、そのXMLの規約に従って通信を行うのが特徴です。※WSDLやEnvelopeの解説は後述してます

SOAP通信の構成要素: WSDL, Envelopeってなんぞや

SOAP APIが厳格な規約に従って通信を行うためには、SOAP独自の構成要素が不可欠です。
そのために使用されるのがWSDLとEnvelopeです。

🔸 WSDL (Web Services Description Language)

WSDLはSOAP APIの「取扱説明書」であり「設計書」にあたります。

これはXML形式のファイルで、APIが提供するすべての情報が定義されています。

  • どんな操作（メソッド）があるか
    • 例: getUserDetails, updateUserStatus
  • 各操作に必要な引数（リクエストデータ）の形式
  • 各操作が返す戻り値（レスポンスデータ）の形式

WSDLがあるおかげで、SOAPクライアントライブラリはこれを読み込むだけで、APIを呼び出すためのJavaやC#などの言語のクラス（スタブコード）を自動生成できます。

実際の案件でもまずはこのWSDLを提出してくださいとご要望をいただきました。
この自動生成機能は、SOAP開発の大きな利点です。
データが明確に定義されているから自動生成しやすいのだと思っています。

🔸 SOAP Envelope（封筒）

SOAPメッセージは、すべてこの「SOAP Envelope」というXML構造に包まれて送られます。これは、SOAPプロトコルとしてのルールを厳守するための必須のラッパータグです。

Envelopeは必ず以下の主要な2つの要素を持ちます。

  1. <Header>: 認証情報、トランザクションIDなど、本質的なデータではないが、通信を管理するために必要な情報を格納します（省略されることもあります）。
  2. <Body>: クライアントが送りたい実際のデータ（リクエスト）、またはサーバーが返すデータ（レスポンス）を格納します。ここに前述のXMLデータが配置されます。

具体的にはこんな感じです。

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns:getUserDataResponse xmlns:ns="sample-service">
            <return>
                <UserData>
                    <user_id>U001</user_id>
                    <user_name>Taro Yamada</user_name>
                    <email_address>taro@example.com</email_address>
                </UserData>
            </return>
        </ns:getUserDataResponse>
    </soap:Body>
</soap:Envelope>

この「必ずEnvelopeに包む」というルールが、SOAP通信がどんなプロトコル（HTTP, SMTPなど）に乗せられても、SOAPメッセージとして識別・処理されることを保証しています。
要するにSOAP用の封筒にデータを入れてくれたら、受け取り側はSOAPって一発でわかるよねって話です。

SOAPを使うメリット・デメリット

そろそろSOAPを使いたくなってきたあなたに、メリット・デメリットの提示です。
前述の通りSOAPは現役です。それは、RESTにはない以下のメリットがあるからです。（もちろんデメリットもある）

✅ メリット：堅牢性と拡張性

  • 高い信頼性: WSDLによりインターフェースが厳密に定義され、意図しない不正なリクエストを排除できる。
  • 高度なセキュリティ・トランザクション対応: WS-Security（認証・認可）やWS-AtomicTransaction（分散トランザクション）といった、SOAP特有の拡張規格が用意されており、各業務の複雑な要求に対応しやすい。
  • 開発支援: WSDLからのスタブコード自動生成により、クライアント側の実装工数を大幅に削減できる。

❌ デメリット：通信の複雑性とオーバーヘッド

  • データ量の増大: XMLのタグが多く、JSONに比べてメッセージサイズが大きくなり、通信オーバーヘッドが発生しやすい。
  • 学習コスト: RESTに比べて、WSDLやSOAP Envelopeといったプロトコル固有の概念を理解する必要がある。
  • 自由度の低さ: 厳格な規約があるため、クライアント側・サーバー側ともに規約を逸脱した柔軟な実装ができない。

とりわけデメリットが目立ち、SOAPはWeb開発競争の中で下火になりました。
どんなサービスもそうですが、一般大衆が自由に拡張していくものは自由度が高いものが選ばれがちです。そういう意味ではRESTに軍配が上がるのも納得です。
この辺の話は有名な著書、「WEBを支える技術」なんかでも言及されてるので読んでみると面白いかもです。

まとめ：もう怖くないよ、SOAP

というわけでデータの形式を軸にSOAPを理解する試みでした。
RESTとSOAPどっちが優秀か、という話はするつもりがなく、そのシステムになにが求められるかによって使い分けできるといいよね、と思っています。

実際にSOAP APIの作成を経験したことで、SOAPは「古い技術」ではなく、「堅牢性・信頼性」を最優先するものなんだな、と実感できたのが個人的に良かったので今回記事にしてみました。

とりあえずいつかSOAPを目にすることがあったら、「うわ、めんど」ではなく「あ、データ構造しっかりしてるやつじゃん」って思ってあげるとSOAPも喜ぶと思います🧴

GitHubで編集を提案
マーベリックスのテックブログ
マーベリックスのテックブログPublication

北海道札幌発・株式会社マーベリックスのテックブログです。 フロントエンド、バックエンド、AWS、AI駆動開発まで、エンジニアの日常と実験を気ままに発信していきます。

Discussion