The SOAP Protocol - Response

In the last post, we covered a sample SOAP Request and deciphered what each part of it means. In this one, we will cover the Response. Remember, Web Service APIs are all about an interface, request and response. In case of SOAP, the interface is a WSDL, the request is a XML specifying a method and parameters, and the response is also an XML as shown below. Let's crack it open

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 30 May 2008 23:59:20 GMT

<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>
    <testPingResponse xmlns="http://api.echosign">
      <pong>
        <message xmlns="http://dto.api.echosign">It works!</message>
      </pong>
    </testPingResponse>
  </soap:Body>
</soap:Envelope>

Quick Notes

1. 200 : The  is the standard HTTP Status code. 200 means success. 
2. <testPingResponse>: Is the root of the response from EchoSign. Could have been named anything
3. <pong>, <message> : We have structured the response to be having a pong element with a message element containing the actual message.

The service provider is flexible to structure the request and response as they want, but once published in a WSDL, it should not change. Any changes in the request and response, will require a new version to be published.

Check out the various versions of the EchoSign SOAP API here. The yellow and green stars represent the new APIs that we added in this version 19 and those that were changed from version 18 respectively

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

diff --brief "SOAP API" "REST API" --exclude="nerdiness"

"You are asking the wrong question. SOAP and REST cannot be compared. SOAP is a protocol. REST is an architectural style." Yes, that is the most pedantic answer that you get when you search for differences between SOAP and REST. And it's correct too! But we are not here to talk about these technical definition differences or protocols, we want to be focusing on the API Design. Both SOAP and REST are paradigms for developing Web Service APIs and in that context they are very much comparable and different

So what are Web Services API? We'll keep the terminology simple in this blog. Web Services API define the interface (contract) between a client and server that is available at a specific URL. The client sends a Request to that specific URL defined by the server. The Request structure follows the interface defined by the API . The server processes the Request and produces a Response  that it sends back to the client. The Response also follows the interface defined by the API. And that's it

This page will server as the landing page to link into all the posts that talk about SOAP and REST structure and differences

1. SOAP Protocol and RESTful API Design

2. Sample mapping between a SOAP and a REST API

Is SOAP Bad?

No, I think that question is bad. When people ask me this question, I ask them back. Is C bad? Is COM bad? People who have grown in the times when Netscape was the most popular browser or Turbo C++ was the favorite compiler will clearly say - No.

C and COM were the best and our favorite back in the day. In some cases they still are. Operating Systems were based on pure C and COM and so are they today. But people have grown to use languages like C++,C#, Java and in general Object Oriented Programming (OOPs) with time. Because, they are better. They resemble the problems at hand better. They make code look better. They represent how we see the real world

SOAP is like C. It is procedural. When C was created, everyone used it to the limits and someone out there realized they needed something object oriented. They wanted to have classes, fields and operations on them. Similarly, someone realized that APIs had to modeled in terms of resources, end-points and operations. And REST was discovered.

Does that make SOAP bad? No. Is SOAP here to stay? Probably. Do 'I' think REST is better? Yes!

WebService::Pair EchoSignAPI(SOAP, REST);

Lets begin by getting introduced to the Web App and it's APIs that we will explore through this blog as a reference

The WebApp is EchoSign (www.echosign.com). EchoSign is an eSignature solution from Adobe that allows senders to get their documents (technically, agreements) signed by one or more recipients. EchoSign supports multiple signature workflows like sequential signing and parallel signing. It also enables scenarios like MegaSign for sending different copies of a document to thousands of different recipients in one go and also multiple recipients signing the same document hosted on our customers website. It allows various security options for preventing the signing and viewing agreement

EchoSign has several integrations with other third party solutions who from within the context of their service want to use EchoSign for sending documents for signature or to enable their own customers to managing their agreements. Examples of such integrations are with Salesforce and Box. All these integrations work by calling into EchoSign APIs and there is where our Pair comes into picture.

Historically, our integrations have used SOAP APIs which is now in Version 19 (yes!) and is documented here:-
https://secure.echosign.com/public/docs/EchoSignDocumentService19

More recently, many of our customers had been requesting for REST APIs and we shipped our Version 1 in December last year which is documented here :-
https://secure.echosign.com/public/docs/restapi/v2

And that's mostly it. I personally understand and learn things better when explained in the context of an example.  Though I had like you to go and use EchoSign as much possible, my focus here would be to talk about API Design using the pair I understand the best and learnt from the most

WebService::Pair<API, API> EchoSignAPI(SOAP, REST);

Welcome to The API Blog

Another blog on APIs. Yes mam, but you also love another pair of shoes too. Yes sir, because you want to watch another game too. Right? Yes, because they are different pair of shoes and a different pair of teams

This Blog is also different, it talks about APIs that were created to transition between the old and new times. And it takes a real example of an API that serves millions of calls every day. And yes, it's a different pair of SOAP and REST APIs

Welcome to my blog which talks about how we bootstrapped REST APIs in EchoSign (www.echosign.com), starting from a well established SOAP API and some of our learning along the way. At your service is an engineer who lives and breathes these APIs every other day with the goal to create the most easily integrate-able e-signature solution in the market

And there goes the usual disclaimer - All the posts and opinions in this blog are my personal ones and do NOT represent the voice or the future direction of a product, APIs or my company. They are what I have learnt and want to contribute back to the API community - some might be good ideas, some not so good ones - but they are my own and not a product or company's take on API

With that, I am relieved to speak an engineer's heart and would like to thank you for being here. Happy reading and would love to hear your comments!