I’ve written a fair bit about web services before. There’s an article explaining how to analyse problems when consuming SOAP web services, how to read the logs and one of my more recent articles was about how to use the REST API. But I’m going to write a bit more about web services, it is after all one of my favourite subjects these days.
You see, I like SOAP. But apparently I’m a bit of an exception, but what I like about SOAP is the thoroughness. It might not always be the easiest to figure out, but if you know how to read it, the WSDL will tell you exactly what services are on offer, what your requests should look like and what you can expect back. As long as you stick to the rules, nothing can go wrong. What are my operations? Check the WSDL. What should the namespace look like? Check the WSDL. What does my SOAP response look like? Check the WSDL. See, you can’t go wrong.
But it’s the rules part that does tend to make it a bit overbearing. I frequently work on problems where there’s disagreement with regards to the exact interpretation of the WSDL. Minor things mostly, but that’s the big weakness of SOAP-based web services. If you don’t stick to the rules 100% all the time it’s not going to work.
Don’t believe me? Check this SOAP request:
It’s an external web service which is consumed with ARS, this is the error that’s returned:
It’s not a particularly helpful error but after a thorough review of the WSDL I realised the namespace for the attributes was wrong. The SOAP request should look like this:
I know that’s correct because the WSDL tells me exactly what the SOAP request should look like:
Notice the attribute element which itself has two attributes (name and form). The element form has a value of unqualified. Here’s what this means:
- Qualified: indicates that this attribute must be qualified with the namespace prefix and the no-colon-name (NCName) of the attribute
- Unqualified: indicates that this attribute is not required to be qualified with the namespace prefix and is matched against the (NCName) of the attribute.
So this would result in: <Customer id='value' /> or possibly: <ns0:Customer id='value' />
We could argue that is not required means that it’s optional, but the fact that they specifically set the attribute form to unqualified can be seen as an indication that the web service does not accept the namespace for the attribute.
Frustrating isn’t it? That tiny detail gave me a lot of headaches and it prevented the whole integration from working. And you really have to get into the details of the WSDL to understand what’s going wrong. Hey I said I like SOAP, I don’t love it.
But I must confess, I absolutely love REST. Yes, I am a true believer in the principles of REST. I love the way it takes advantage of the strengths of the architecture of the web, I love its focus on simplicity, on readability.
I’m not going to get into too much detail into the principles of REST, what I want to look at is how the implementation of a REST-based web service different from SOAP. The principles of REST-based web services are based on a more intuitive way to communicate with another machine. The result is a simpler interface with simpler requests and responses that are easier to read and understand. Consider the following SOAP request:
So now we’re GETting data. The URL makes a lot more sense as well and compared to the SOAP request is a lot easier to read.
One of the principles of a REST-based web service is that you don’t require prior knowledge of the web service other than its base URL. BMC’s implementation isn’t true RESTful in that sense as you do need some information to get you started. You need to know how to login and logout and you do need some degree of familiarity of the format of the requests. But other than that it’s really easy to use.
I think SOAP lends itself quite well for communication where two machines are already able to deal with SOAP’s complexities. ARS for example allows you to consume an external SOAP-based web service and it’s just a matter of mapping the elements to the various fields and integrating this in the workflow. You don’t really have to deal with the interpretation of the WSDL or the construction of SOAP requests. ARS does it for you, and unless something goes wrong the web service integration works perfectly.
But if you want to integrate with ARS using a programming language, REST is the better choice. For example, if you use Java and you’re interacting via SOAP there’s quite a lot to it. You can of course just hardcode the whole HTTP request but if you want to do it properly you need rely on an external library like AXIS. There’s nothing wrong with that but it does suddenly get quite complicated. Considering you only want to send small requests to check a status or to get a record, you need a lot of code to get this to work.
That’s where REST’s strengths come in, because using the REST API it suddenly gets a lot easier to do. Since we don’t have to follow the strict rules specified in the WSDL and since the requests are lot smaller it’s actually quite easy to get stuff done. Other than the usual networking libraries I don’t need any 3rd party libraries or frameworks to interact with the system, and since the API is intuitive it’s a lot easier to construct my requests.
Want to know more? I'll be talking about this at Session 233: Getting the Most out of Your Web Services Integration at BMC Engage. We’ll have a detailed look at SOAP, REST and of course at how you’d actually implement all of this. Join me there to learn more!
Don't forget to follow me on twitter!