Wednesday, December 17, 2014

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=""
      xmlns:xsd="" xmlns:xsi="">
    <testPingResponse xmlns="http://api.echosign">
        <message xmlns="http://dto.api.echosign">It works!</message>

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.

SOAP API Method changesThe 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

Thursday, December 11, 2014

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
Content-Length: 325
<soap:Envelope xmlns:soap=""
      xmlns:xsd="" xmlns:xsi="">
    <testPing xmlns="http://api.echosign">

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. is the host to the web service. 
Transport Protocol (https://) + Host ( + 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

Tuesday, December 9, 2014

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

2. Sample mapping between a SOAP and a REST API

Friday, December 5, 2014

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!

Monday, December 1, 2014

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 ( 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:-

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 :-

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);