Thursday, September 24, 2009

REST Blueprints and Reference Architectures

Okay so the REST-* stuff appears to have rapidly descended into pointless diatribe which is a shame. One of the questions is what it should be instead (starting with REST-TX and REST-Messaging wasn't a great idea) and around a few internal and external discussions its come down to a few points
  1. What is "best practice"
  2. What is the standard way to document the interactions available & required
  3. How do we add new MIME types
Quite a bit of the technical basics have been done but before we start worrying about a "standard" way of defining reliability in a REST world (yes GET is idempotent.... what about POST?) we should at least agree on what good looks like.

Back in the day Miko created the "SOA Blueprint" work around Web Services, an attempt to define a concrete definition of "good", unfortunately it died in OASIS (mainly due to lack of vendor engagement) but I think the principles would be well applied here.

The other piece that is good (IMO) is the SOA Reference Model, Roy Fielding's paper pretty much defines that reference model but what it doesn't have is a reference architecture. Saying "The internet is the reference architecture" doesn't really help much as that is like saying that a mountain is a reference architecture for a pyramid.

Now one of the elements here is that there appears to be some parts of the REST community that feel that Enterprise computing must all "jump" to REST and the internet or are in fact therefore irrelevant to REST. This isn't very constructive as the vast majority of people employed in IT are employed in just those areas. B2B and M2M communications with a decent dose of integration are the standard problems for most people, not how to integrate with Yahoo & Amazon or build an internet facing website.

For the enterprise we have to sacrifice a few cows that hopesfully aren't sacred but I've heard bandied around
  1. You can't just say "its discoverable" - if I'm relying on you to ship $500m of products for me then I don't want you messing around with the interface without telling me
  2. You can't just say "late validation" - I don't want you making a "best guess" at what I meant and me doing the same, I want to know that you are shipping the right thing to the right place
  3. You can't just say "its in the documentation" - I need something to test that you are keeping to your side of the bargin, I don't want just English words telling me stuff I want formal definitions... contracts.
  4. You can't just say "look at this URI" - we are embarking on a 5 month project to build something new, you haven't done your stuff yet, you don't have a URI yet and I need to Mock up your side and you need to Mock mine while we develop towards the release date. Iterative is good but we still need to have a formal clue as to what we are doing
  5. You can't say 'that isn't REST' if you don't have something objective to measure it against
So what I'd suggest is that rather than having the REST-* piece looking at the technical standards we should really be focusing on the basics mentioned above. We should use Roy's paper as the Reference Model from which an enterprise Reference Architecture can be created and agree on a standard documentation approach for the technical part of that reference architecture.

In other words
  1. REST Reference Model - Roy's paper - Done
  2. REST Reference Architecture - TBD and not HTTP centric
  3. REST Blueprints - Building the RA into a concrete example with agreed documentation approaches (including project specific MIME types)
Right now burn me at the stake as a heretic

Technorati Tags: ,


Morten said...

Could you clarify what you mean about "not http centric"?

Steve Jones said...

Lots of REST people make the point that REST isn't about HTTP, HTTP just "happens" to be the best reference case. So my point is that a reference architecture shouldn't be simply about HTTP but should be about the principles of REST as applied to architecture.

stu said...

The main issue with not being HTTP-centric is that Roy's thesis is rather abstract, and doesn't get into certain practical details.

As such, I'd suggest "The Architecture of the World Wide Web" as a useful complementary document, in that it provides more concrete details on a real RESTful architecture:

Steve Jones said...

Makes sense to me, I'm just trying to not start a war ;) The RA should go into more practical details while the blueprints should be absolutely at the coal-face. Personally I wouldn't object if people felt the RA should be HTTP centric, just as long as its a model that applies to enterprise style cases as well as the whole WWW.

Part of the question as well is where does it belong? OASIS could be one easy landing place as a precursor to a more formal adoption (if required) at the likes of IETF.

Graham said...

Has anyone proposed a reference case that isn't HTTP based? Having briefly thought about it wouldn't a reference case built on (say) JMS be so markedly different from the HTTP reference case that they would be essentially divergent?

I'm not saying we shouldn't try, I'm just standing at the foot of the mountain thinking how high it really is!

Steve Jones said...

Not disagreeing, just trying to stop a flame war from those who say that REST != HTTP and that HTTP is "just" an implementation of REST.

Bill Burke said...

So you're saying we have to solve those fundamental IT problems before moving forward? I disagree. It should be done in parallel.

I prefer an iterative approach where you "guess" at a few best practices and abstractions then prototype real applications and services to flush out the details. Create a feedback loop.

As far as defining contracts that Enterprise IT (and developers in general) desire, the media type and link relationship definitions define this contract.

As for the "Mocking" example you gave, there IMO really is no different from REST and traditional RPC interface development. For an interface you have to agree upon the methods and their parameters. For REST, the methods are already known, you just need to define the parameter (media type) and related (linked-to) resources. The media type definitions define how you use those methods and links define transitions to other resources.

I do think we need a well defined way for describing these things. But personally, I'm more interested in the what and why, not the how. Plus, there already are a few great examples on how you define and put this stuff together. Specifically Atom.

Steve Jones said...


Haven't people done enough REST applications at this stage to agree to a common best practice?

There is a big difference between Mocking with WS-* where you have a WSDL. You give the WSDL to someone and they can create the Mock straight away. With REST what do you hand over? I agree that there is lots of thinking and good work out there, what I'm suggesting is a getting a group of people with that experience together to agree on a set of guidelines and best practices which newer people can follow and which enterprise users can rely upon.

Integral ):( Reporting said...

>> Haven't people done enough REST applications at this stage to agree to a common best practice?

The answer is clearly "no", people have built RESTful APIs but they have not built any real application with it (ERP, CRM, ...). Otherwise they would show up everywhere. After years of REST hype, you would think someone would want show off and explain how fast it was to build it with HATEOAS, the uniform interface, the media types and what not.

This presentation on InfoQ:

is the closest I have seen that describes an "application" but as you can see the author is quite evasive on what he really has built. Is it just a bunch of webparts? or an "application"?

Anyways, I am sure you guys will create the same kind of useless prose as SOA-RM and SOA-RA, not to mention SoaML. So I totally support your idea...

Jean-Jacques Dubray