Simon Willison's Weblog: soap

What information do you feel is most valuable when integrating a Web API (REST or SOAP)?

2013-10-04T18:57:00+00:00

My answer to What information do you feel is most valuable when integrating a Web API (REST or SOAP)? on Quora

A really good API explorer
Comprehensive documentation of the response format, including what happens if certain fields are missing (empty string, null value, missing key?)
Comprehensive documentation of the available request parameters, including allowed values
What are the rate limits?
What is returned if there is an error?

What is a good, simple SaaS tool for testing SOAP calls?

2013-09-23T13:20:00+00:00

My answer to What is a good, simple SaaS tool for testing SOAP calls? on Quora

I doubt you'll find one. The words "Simple" and "SOAP" don't deserve to appear in the same sentence, and SOAP is massively unfashionable these days (for good reason) so you're unlikely to find any modern SaaS companies developing tools for it.

Tags: soap, quora, saas

Explaining REST to Damien Katz

2008-08-17T23:19:32+00:00

Explaining REST to Damien Katz

I didn’t know that it was Mark Baker back in 2002 who first pointed out that SOAP was flawed because it ignored the architecture of the Web as defined by Roy Fielding’s Ph.D thesis.

Tags: damien-katz, dare-obasanjo, history, mark-baker, rest, royfielding, soap

Multi-Inflection-Point Alert

2008-04-26T18:48:57+00:00

Multi-Inflection-Point Alert

Dammit, Tim, stop giving away our competitive advantages!

Tags: bigtable, couchdb, java, python, rails, rest, simpledb, soap, tim-bray

Google AJAX Search API: Flash and Server Side Access

2008-04-22T19:16:50+00:00

Google AJAX Search API: Flash and Server Side Access

Over a year after Google shot down their SOAP Search API, they’ve quietly released a JSON based one under the guise of supporting “Flash and other non JavaScript environments”. Comes with the strange requirement that an HTTP referer be sent with every request; the API key is optional.

Tags: ajax, apis, google, json, search, soap, web-services

WS-dämmerung

2007-11-22T09:49:02+00:00

WS-dämmerung

Tim Bray collects the latest round of WS-* repenting, which saves me from linking to them individually.

Tags: soap, tim-bray, web-services, ws-star

soaplib

2007-02-12T22:26:53+00:00

soaplib

New open-source Python SOAP library, with a pleasantly Pythonic looking API.

Via Jonathan LaCour

Tags: jonathan-lacour, python, soap, soaplib, web-services

Quoting Nick Gall

2007-01-27T13:55:30+00:00

Web Services based on SOAP and WSDL are "Web" in name only. In fact, they are a hostile overlay of the Web based on traditional enterprise middleware architectural styles that has fallen far short of expectations over the past decade.

— Nick Gall, VP Gartner

Tags: gartner, soap, web-services, wsdl

Why JSON isn't just for JavaScript

2006-12-20T23:49:34+00:00

Dave Winer's discovery of JSON (and shock that "it's not even XML") has triggered an interesting discussion thread, on his blog and elsewhere. Plenty of people have re-assured him (and themselves) that it's only used for JavaScript - it's convenient in the browser but irrelevant elsewhere.

That simply isn't true. Let's look at the problem JSON solves:

I have a data structure on server / platform / programming environment A. I want to use it on server / platform / programming environment B.

Surely that problem has been solved a hundred times before? That's what XML's for, right?

Here's an example data structure, of the kind you might want to transmit from one place to another (represented as a Python dictionary; mentally replace with the syntax from your programming language of choice).

person = {
  "name": "Simon Willison",
  "age": 25,
  "height": 1.68,
  "urls": [
    "http://simonwillison.net/",
    "http://www.flickr.com/photos/simon/",
    "http://simon.incutio.com/"
  ]
}

It's a simple example, but it demonstrates the core data structures that any modern dynamic language is likely to support: strings, integers, floating points, hashes (or dictionaries or associative arrays depending on terminology) and lists (or sequences or arrays).

So how do I represent this in a language-neutral format? Obviously I can use XML. I could invent my own custom representation:

<person>
  <name>Simon Willison</name>
  <age>25</age>
  <height>1.68</height>
  <urls>
    <url>http://simonwillison.net/</url>
    ...
  </urls>
</person>

But this means writing a bunch of boilerplate code. I need code to build the XML format, and code to parse it (using SAX or DOM or whatever) at the other end. I need to write this code in every language/platform that I want to communicate with. That's a lot of extra effort!

So let's be smarter about this and reuse an existing format. If there's an XML-based standard for the exact data I'm representing I could use that; if there are good libraries supporting it for the languages that I'm using I don't have to write any extra parsing code.

If that isn't the case, I need to look at XML standards that can represent our standard data types. As Dave points out, our principle options here are SOAP and XML-RPC.

By most accounts SOAP is a total pain to get anything done with, so let's look at XML-RPC. XML-RPC encodes the exact data types we want, but wraps them up in a RPC mechanism. I have no need for any of the <methodCall> / <methodResponse> boiler plate; I just want to represent the data, not specify a remote method to call.

So I could use a subset of XML-RPC that's just the data representation - in fact, that's really not a bad idea. But then I'd have to figure out how to get the various XML-RPC libraries to parse just the data structures without barfing at the lack of an envelope.

I also face the problem that XML-RPC isn't particularly human-readable. In fact, XML itself tends not to be brilliantly readable: the data gets lost among the angle brackets.

Enter JSON. The smartest thing about JSON is that it addresses the need for a light-weight standard for representing those core data types and, rather than inventing a new one, uses a subset of an existing one: ECMAScript, more commonly known as JavaScript.

JavaScript has excellent syntax for both object and array literals (something Java could certainly learn from); remember, in JavaScript an object is basically an associative array. JSON takes that syntax and makes it generally applicable. Because JavaScript is a programming language, JSON syntax is naturally readable and writable by human beings.

If you take away the assignment statement the Python example I gave earlier is also valid JSON. JSON is also a subset of YAML, an earlier attempt at a human readable/writable serialization format. More importantly, JSON libraries almost certainly exist for your language of choice (there are 24 languages represented in the list on JSON.org). Most of them provide two functions - json_encode($data) and json_decode($json) - and that's all you need.

The sweet spot for JSON is serializing simple data structures for transfer between programming languages. If you need more complex data structures (maybe with some kind of schema for validation), use XML. If you want to do full blown RPC use SOAP or XML-RPC. If you just want a light-weight format for moving data around, JSON fits the bill admirably.

What do we lose from not using XML? The ability to use XML tools. If you're someone who breathes XSLT that might be a problem; if like me your approach when faced with XML is to parse it in to a more agreeable data structure as soon as possible you'll find JSON far more productive.

Tags: dave-winer, javascript, json, soap, xml, xml-rpc

When to put the web into Web Services

2003-12-11T01:10:16+00:00

When to put the web into Web Services

aka “What’s SOAP actually useful for?”

Tags: soap

PHP SOAP Documentation

2003-04-11T15:02:31+00:00

Finally some good documentation on using SOAP with PHP: PEAR::SOAP Client Fast Start and Extending PEAR::SOAP WSDL, both from the excellent phpPatterns.

Tags: php, soap

Lively discussion on SOAP

2003-04-04T14:54:21+00:00

If you get the basic idea of web services but are still looking to get your head around SOAP (I know I am) the lively discussion currently taking place in Sam Ruby's comment section looks like a great place to start.

Tags: sam-ruby, soap

The Two Way Web

2002-07-06T22:14:01+00:00

Dave Winer: The Two Way Web. The Two-Way-Web is a vision for the Web as an easy writing and publishing environment. This is an old essay from March 2001 (I only found it today) which describes a vision of a web where content can be quickly and easily edited through a variety of tools, which communicate with content management systems using XML-RPC and SOAP. This is all stuff I've been thinking about recently, so it looks like I'm only a year and a half behind Dave ;)

Tags: dave-winer, soap, xml-rpc

XML request object

2002-07-03T23:50:21+00:00

Using the XML HTTP Request object (via techno weenie) is an excellent tutorial covering remote XML loading capabilities in both IE and Mozilla, along with instructions on how to make SOAP requests using this technology.

Tags: soap, xml