Duncan Cragg: So - let's get straight to my argument: I claim that your SOAP APIs, as instances of the SOA style, won't scale or interoperate as well as they would if they were implemented in the REST style. Which, in the form of the Web, has largely proven scalability and interoperability.

eBay Architect: SOA won't scale or interoperate and REST will? You've got some explaining to do there: the whole industry is going SOA crazy, and we're following that trend. You'll need to give specific examples.

DC: OK.

eA: And even if it is true, we don't care about scalability and interoperability: we have quite low traffic on our APIs - certainly compared to port 80; plus we're eBay so we don't need to interoperate with anyone.

DC: That's true now, but if the Web 2.0 vision comes together, you may care: your API traffic could increase dramatically. It would be better to be the one prepared for the scale of the API-Web!

Can you really argue in your company that you don't need to be scalable? What if your port 80 traffic needs to be routed to your APIs for some reason?

eA: Maybe.

DC: As for interoperability, you could be excluded from Web 2.0 industry-boosting consortia, or excluded from perhaps hugely popular Web 2.0 applications in the future...

Interoperability raises the level of the market as a whole. Market players shouldn't differentiate on what's common to them, they should differentiate on the level above.

It also depends on the value you place on having happy customers who don't have to do the same thing multiple ways or multiple times.

eA: Ha! I'm sure there's a name for that style of argument!

So, let's say we want to be good scalable and interoperable citizens in a future Web 2.0 world: show me how REST can help us more than SOA and SOAP do!

Getting Data

DC: OK, let's look at your SOAP API. There are 72 function calls in there that begin with 'Get'. Each one specifies a particular piece of data that you can fetch.

eA: Yes, our API is extremely rich.

DC: Sure, but you don't need a new function call for everything you can get from your system: you can just use HTTP GET!

eA: OK, but it's just data going in to request the information, then data coming back out again. What difference does it make whether we use HTTP or SOAP to carry those messages? You've just moved the name onto your URI!

DC: It's not just any 'data going in': the URI can be passed around for anyone to re-use. This URI is more interoperable because so much deployed software understands it. No-one understands 'GetSearchResults()'!

eA: OK.

DC: Another example of how the URI can glue things together is that the data returned from your GETs can have more URIs in them, ready to go! You won't get data from your Web Service with 'GetItem()' in it..

eA: Heh - I s'pose not.

DC: REST also talks about the formats of the data behind a URI. In a GET, the response data is given a Content-Type, and there's an expectation that clients will understand the types of data being returned: interoperability comes from broad standardisation of return data.

eA: But we return XML, and our schemas are published. They're specific to our application anyway. That wouldn't change with REST.

DC:The explicit statement of Content-Type reflects a culture of agreement forced by the sharability of URIs: your URIs are more sharable when more clients understand the data they dereference to.

On the other hand, the culture of SOA is to declare custom WSDL and custom XML schemas.

Like I said, one day you may care about interoperability, and having an architecture that puts a high value on content type and schema standardisation, as REST does, puts you one step ahead.

eA: We'll see.

DC: You can also gain scalability by partitioning on those URIs.

eA: We already do plenty of partitioning of our data and functions.

DC: Yes, but URI partitioning cuts right through the system in a very simple way: your partitioning is an application-specific optimisation which has to be hand-coded behind the SOAP interface.

eA: Mmm. Maybe.

DC: Another benefit of using HTTP over using SOAP is that you get cacheing built in to the architecture, which you can start using as soon as you ask for it in the headers. This boosts scalability.

eA: OK, that's fair. Our clients would have to write their own caches, should they need them. But in general we advise against cacheing our data and don't put expiry on them or have not-modified checks.

DC: Which is where you're potentially inefficient.

eA: Maybe. We internally cache things like the data behind GetCategories, and advise our users how to cache it themselves.

DC: Again - it's application-specific.

So - even in the simple cases of fetching data, REST has given you much greater scalability and interoperability than your SOAP interface - as well as a simpler, more generic approach.

And we're only one-ninth of the way through our conversation!

eA: How do you know that??

DC: Aaah...

(c) 2006 Duncan Cragg

In Part 2: Setting Data.

Note that the opinions of our imaginary eBay Architect don't necessarily represent or reflect in any way the official opinions of eBay or the opinions of anyone at eBay.

Indeed, I can't guarantee that the opinions of our real blogger necessarily represent or reflect in any way the official opinions of Roy Fielding...