The SOAP Protocol

SOAP is a protocol which means that it has a defined structure to it. SOAP is used in multiple ways for multiple purposes, but whenever we talk about SOAP in this blog, it will be limited to SOAP in Web Services API. The EchoSign API SOAP Header describes what SOAP means for a Web Service, in this case EchoSign quite well. In our SOAP APIs, we use SOAP over HTTP. The simplest SOAP request you can try with EchoSign is testPing that can be used to confirm that your have the right Web Service URL, are able to successfully communicate with it using SOAP (send a Request and get a Response), and have a valid apiKey. Let's decipher the testPing page

POST /services/EchoSignDocumentService HTTP/1.1
SOAPAction: ""
Content-Type: text/xml; charset=UTF-8
Host: secure.echosign.com
Content-Length: 325

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <testPing xmlns="http://api.echosign">
      <apiKey>YOURAPIKEY</apiKey>
    </testPing>
  </soap:Body>
</soap:Envelope>

Few things to note here

1. SOAP uses XML as the language for communication

2. <soap:Envelope> with the XML Namespace (xmlns) is required to indicate that this is a SOAP Request

3. <soap:Body> is the root SOAP element which describes the Request and Response

The items in bold black are generic to SOAP Web Service and those in bold red are specific to EchoSign

SOAP Protocol

1. POST : The SOAP request always requires a HTTP body, hence the HTTP method is POST. More about HTTP Methods in a future POST (these are very relevant in REST), but for now lets assume this is always POST in case of SOAP
2. SOAPAction : Empty means, intent in HTTP Request URI. If you are really interested, check here, else OK to ignore

3. Content-Type : SOAP uses XML as the language for communication and hence this is always text/xml

4. <soap:Envelope> with the XML Namespace (xmlns) is required to indicate that this is a SOAP Request. 
5. <soap:Body> is the root SOAP element which describes the Request and Response

Web Service (EchoSign) Specific

1. /services/EchoSignDocumentService represents the Web Service Path

2.  secure.echosign.com is the host to the web service. 

Transport Protocol (https://) + Host (secure.echosign.com) + Web Service Path (/services/EchoSignDocumentService) gives the complete SOAP Web Service URL

3. <testPing> is the EchoSign specific method that we want to call

4. <apiKey> is a parameter that our testPing method takes. In this case, the value is kept to be a filler string YOURAPIKEY. While trying this method, we will replace this with a real API Key. API Key in EchoSign is something that uniquely identifies your user/account and we will learn how to issue one in an upcoming POST