In an exclusive nine-part dialogue with an imaginary eBay Architect, we present an accessible discussion of the REST vs. SOA issue.
Although eBay have what they call a 'REST' interface, it is, in fact, a STREST interface, and only works for one of the many function calls that they make available via SOAP (GetSearchResults).
In this dialogue series, I argue the case for eBay to adopt a truly REST approach to their integration API.
Part 2: Setting Data
Duncan Cragg: Now, let's look at those calls in eBay's SOAP API that are expected to change data. There is often a corresponding 'Get' function.
Examples are GetTaxTable, SetTaxTable and GetMyMessages, ReviseMyMessages, ReviseMyMessagesFolders, DeleteMyMessages, etc.
Here, there is an implicit model of data (or lists of data) that you can look at, modify, delete, etc.
eBay Architect: It's not just data: Tax Tables and Messages have meaning and behaviour internally to the server.
DC: Yes, but we're talking about what the API is telling us, here. It says things like GetTaxTable and SetTaxTable!
We'll come on to business processes later, but just look at the simple stuff first.
eA: OK, so what's the benefit of doing these calls in HTTP, through POST or whatever?
DC: Again, scalability and interoperability.
In the same way as with GET, you can partition your POST handling across the URI space. Have your Tax Tables and Message folders handled by many machines, split by their URIs. This is an example of the inherent parallelisability of the Web's architecture.
eA: We do partition by function: search, display, sell.
DC: Sure, but you had to 'hard-code' this partition: to use specific heuristics and code to achieve it: URI-based partitioning is much more generic and flexible, and can be much finer-grained. You seldom get single-point of failure or bottleneck issues with good REST architectures.
eA: If you say so.
DC: Interoperability again derives from the standardisation of the Content-Types and the schemas of POSTed data. When you know the meaning of the data you fetch, you also know how to try and change it, if you can.
eA: In HTML, you actually get presented a form in some GET data which explicitly tells you what to POST back - what the 'schema' is.
What's the equivalent in a general REST integration context where it's machines that are doing the POSTing?
DC: Well, the same applies, insofar as the GET data effectively tells you what any return data should look like. However, this time it's in an implicit way.
Where, in the read context, you understood what to do with a given content type you'd fetched, now, in the write context, you further understand what you can send back to it again.
eA: Can you give examples, please? The Tax Table perhaps?
DC: Straightforward data updating is the simplest case - it's the same content type coming out as going back in. You see a Tax Table at some URI, then you just PUT a new Tax Table back at that URI to try and replace it.
All the API function calls beginning 'Set' should probably be implemented this way.
eA: OK, so how does REST implement our Message API functions?
DC: An example of a data format that implies its edit capabilities by reference to a standard is Atom syndication.
You can GET a list of Atom entries, then POST a new one according to the Atom Publishing Protocol (APP) specification. You POST, not to a 'service' or handler, but to the URI of the actual collection you're adding to.
eA: So what's that got to do with our Messages?
DC: The eBay Message lists are a great candidate for using this approach, with the benefit that any (recent) feed reader can be used to view them, and an APP-compliant client used to manage them.
All the API function calls beginning 'Add' should probably be implemented in the same way APP adds new entries, or you should consider using APP itself to implement them.
eA: OK, so we can replace some calls with a standard set of REST interactions. But clients still have to know about Tax Table schemas, User Preferences schemas, Message schemas, etc.
It's not enough to simply know about HTTP and HTML to be interoperable any more, like a browser does. It's not even enough to just know APP.
Surely interoperability stops when the content types and schemas start to proliferate like this?
DC: Schema proliferation is SOA's problem - so I'm glad you brought it up! It's baked in to the SOA mindset that it's OK to design your own interfaces and schemas from scratch each time.
Conversely, the expectation and culture in the Web and especially in the REST-aware community is to constantly look out for opportunities to conform and to standardise schemas and interactions, and to build on layers below that are already standardised. It's a side-effect of the shareability of URIs.
With REST you get interoperability at many levels above the byte-transfer of HTTP. Content type understanding and standardisation can occur all the way up from characters to Tax Tables.
eA: I'm not sure I get this.
DC: OK: there is some code that understands basic HTTP GET and PUT, and UTF-8 characters - and doesn't need to know what a Tax Table is - some that understands UTF-8 plus XML, some that understands that plus Atom, or plus XHTML, then XHTML tables and Microformats like hCalendar, hCard (and hAtom!), then conference schedules using hCalendar and hCard. Tax Tables can perhaps use XHTML tables.
Clients may or may not need to know what the schema of a Message looks like internally in order to be able to do useful work with Messages at their level of understanding - from character stream up to APP.
eA: I'm not sure how general auction schemas fit in there.
DC: You never know, your eBay schemas might be taken into account when coming up with new standard content types for e-commerce!
eA: Hopefully. We could always put everything into XHTML tables for you!
DC: Ha! Go for it. Having done some HTML scraping myself, I'd welcome such semantics!
eA: Right, it's OK when we're just talking data that you can read and write - HTTP, APP, REST, whatever may be great for that - but our API has much more complex business functions in it that don't fit that simplistic model.
There's a whole load of functions in our API that aren't just about getting and setting data or collections of data. Some are eBay- or auction-specific.
DC: This is one of the Myths of REST - that it's just for simplistic reading and writing of data.
It's a actually a myth that's often propagated by the REST community itself, especially with their over-emphasis on the Four HTTP Verbs, which seem to map so conveniently onto Create, Read, Update and Delete.
eA: But they do map so well - I thought that was 'good' REST...
DC: It is often good, but can detract from the whole goodness!
One consequence of this mapping it that people inevitably go on to see an analogy between REST and databases, and then start to expect transactions and other database features.
Another consequence of the database analogy is that resources are seen as lifeless servants of the active client: it takes away responsibility from a resource to be master of its own destiny.
This then causes confusion (even within the REST community) about the power of the client and even the very meaning of such basics as the PUT method.
The fact is, GET and POST are more than enough to be REST compliant. This cut-down pair also help focus the mind on URIs, two-way content transfer, content type or schema and on the responsibilities of each resource as active players in an integration scenario.
eA: Sounds like a minority REST view - any support from a REST luminary for that?
And recently, there has been further high-level support from Sam Ruby and Leonard Richardson in their manifesto for an upcoming book.
eA: I bet you still get told off, but it sounds reasonable to me.
DC: So, to summarise: use GET to read data, then POST back to the same URI to suggest changes to the resource there.
All based on a given level of understanding and interpretation of the content type and any corresponding interaction standards.
Interoperability and scalability in a nutshell!
Now I will explain how there's more to REST than simple reading and (attempted) writing of resources. We're still only two-ninths done...
(c) 2006 Duncan Cragg
In Part 3: Business Functions.
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...