InfoQ Homepage Articles Addressing Doubts about REST

Leia em portuguÃªs

This item in japanese

This item in chinese

Invariably, learning about REST means that you’ll end up wondering just how applicable the concept really is for your specific scenario. And given that you’re probably used to entirely different architectural approaches, it’s only natural that you start doubting whether REST, or rather RESTful HTTP, really works in practice, or simply breaks down once you go beyond introductory, “Hello, World”-level stuff. In this article, I will try to address 10 of the most common doubts people have about REST when they start exploring it, especially if they have a strong background in the architectural approach behind SOAP/WSDL-based Web services.

### 1. REST may be usable for CRUD, but not for “real” business logic

This is the most common reaction I see among people who are skeptical about REST benefits. After all, if all you have is create/read/update/delete, how can you possibly express more complicated application semantics? I have tried to address some of these concerns in the introductory article of this series, but this point definitely merits closer discussion.

First of all, the HTTP verbs - GET, PUT, POST, and DELETE - do not have a 1:1 mapping to the CRUD database operations. For example, both POST and PUT can be used to create new resources: they differ in that with PUT, it’s the client that determines the resource’s URI (which is then updated or created), whereas a POST is issued to a “collection” or “factory” resource and it’s the server’s task to assign a URI. But anyway, back to the question: how do you handle more complex business logic?

Any computation calc(a, b) that returns a result c can be transformed into a URI that identifies its result — e.g. x = calc(2,3) might become http://example.com/calculation?a=2&b=3. At first, this seems like a gross misuse of RESTful HTTP — aren’t we supposed to use URIs to identify resources, not operations? Yes, but in fact this is what we do: http://example.com/sum?augend=2&addend=3 identifies a resource, namely the result of adding 2 and 3. And in this particular (obviously contrived) example, using a GET to retrieve the result might be a good idea — after all, this is cacheable, you can reference it, and computing it is probably safe and not very costly.

Of course in many, if not most cases, using a GET to compute something might be the wrong approach. Remember that GET is supposed to be a “safe” operation, i.e. the client does not accept any obligations (such as paying you for your services) or assume any responsibility, when all it does is follow a link by issuing a GET. In many other cases, it’s therefore more reasonable to provide input data to the server so that it can create a new resource via POST. In its response, the server can indicate the URI of the result (and possibly issue a redirect to take you there). The result is then re-usable, can be bookmarked, can be cached when it’s retrieved … you can basically extend this model to any operation that yields a result — which is likely to be every one you can think of.

### 2. There is no formal contract/no description language

From RPC to CORBA, from DCOM to Web Services we’re used to having an interface description that lists the operations, their names, and the types of their input and output parameters. How can REST possibly be usable without an interface description language?

There are three answers to this very frequently asked question.

First of all, if you decide to use RESTful HTTP together with XML — a very common choice — the whole world of XML schema languages, such as DTDs, XML Schema, RELAX NG or Schematron are still available to you. Arguably, 95% of what you usually describe using WSDL is not tied to WSDL at all, but rather concerned with the XML Schema complex types you define. The stuff WSDL adds on top is mostly concerned with operations and their names — and describing these becomes pretty boring with REST’s uniform interface: After all, GET, PUT, POST and DELETE are all the operations you have. With regards to the use of XML Schema, this means that you can use your favorite data binding tool (if you happen to have one) to generate data binding code for your language of choice, even if you rely on a RESTful interface. (This is not an entirely complete answer, see below.)

Secondly, ask yourself what you need a description for. The most common — albeit not the only — use case for having some description is to generate stubs and skeletons for the interface you’re describing. It is usually not documentation, since the description in e.g. WSDL format tells you nothing about the semantics of an operation — it just lists a name. You need some human-readable documentation anyway to know how to call it. In a typical REST approach, what you would provide is documentation in HTML format, possibly including direct links to your resources. Using the approach of having multiple representations, you might actually have self-documenting resources — just do an HTTP GET on a resource from your browser and get an HTML document containing data as well as a list of the operations (HTTP verbs) you can perform on it and the content types it accepts and delivers.

Finally, if you insist on using a description language for your RESTful service, you can either use the Web Application Description Language (WADL) or — within limitations — WSDL 2.0, which according to its authors is able to describe RESTful services, too. Neither WADL nor WSDL 2 are useful for describing hypermedia, though — and given that this is one of the core aspects of REST, I’m not at all sure they’re sufficiently useful.

### 3. Who would actually want to expose so much of their application’s implementation internals?

Another common concern is that resources are too low-level, i.e. an implementation detail one should not expose. After all, won’t this put the burden of using the resources to achieve something meaningful on the client (the consumer)?

The short answer is: No. The implementation of a GET, PUT or any of the other methods on a resource can be just as simple or complicated as the implementation of a “service” or RPC operation. Applying REST design principles does not mean you have to expose individual items from your underlying data model — it just means that instead of exposing your business logic in an operation-centric way, you do so in a data-centric way.

A related concern is that not enabling direct access to resources will increase security. This is based on an old fallacy known as “security by obscurity”, and one can argue that in fact it’s the other way round: By hiding which individual resources you access in your application-specific protocol, you can no longer easily use the infrastructure to protect them. By assigning individual URIs to meaningful resources, you can e.g. use Apache’s security rules (as well as rewriting logic, logging, statistics etc.) to work differently for different resources. By making these explicit, you don’t decrease, you increase your security.

### 4. REST works with HTTP only, it’s not transport protocol independent

First of all, HTTP is most emphatically not a transport protocol, but an application protocol. It uses TCP as the underlying transport, but it has semantics that go beyond it (otherwise it would be of little use). Using HTTP as a mere transport is abusing it.

Secondly, abstraction is not always a good idea. Web services take the approach of trying to hide many very different technologies under a single abstraction layer — but abstractions tend to leak. For example, there is a huge difference between sending a message via JMS or as an HTTP request. Trying to dumb widely different options down to their least common denominator serves no-one. An analogy would be to create a common abstraction that hides a relational database and a file system under a common API. Of course this is doable, but as soon as you address aspects such as querying, the abstraction turns into a problem.

Finally, as Mark Baker once coined: “Protocol independence is a bug, not a feature”. While this may seem strange at first, you need to consider that true protocol independence is impossible to achieve — you can only decide to depend on a different protocol that may or may not be on a different level. Depending on a widely accepted, officially standardized protocol such as HTTP is not really a problem. This is especially true if it is much more wide-spread and supported than the abstraction that tries to replace it.

### 5. There is no practical, clear & consistent guidance on how to design RESTful applications

There are many aspects of RESTful design where there are no “official” best practices, no standard way on how to solve a particular problem using HTTP in a way conforming to the REST principles. There is little doubt that things could be better. Still, REST embodies many more application concepts than WSDL/SOAP-based web services. In other words: while this criticism has a lot of value to it, it’s far more relevant for the alternatives (which basically offer you no guidance at all).

Occasionally, this doubt comes up in the form of “even the REST experts can’t agree how to do it”. In general, that’s not true — for example, I tend to believe that the core concepts I described here a few weeks ago haven’t been (nor will they be) disputed by any member of the REST community (if we can assume there is such a thing), not because it’s a particularly great article, but simply because there is a lot of common understanding once people have learned a little more than the basics. If you have any chance to try out an experiment, try whether it’s easier to get five SOA proponents to agree on anything than trying to get five REST proponents to do so. Based on past experience and long participation in several SOA and REST discussion groups, I’d tend to bet my money on the REST folks.

### 6. REST does not support transactions

The term “transaction” is quite overloaded, but in general, when people talk about transactions, they refer to the ACID variety found in databases. In an SOA environment — whether based on web services or HTTP only — each service (or system, or web app) implementation is still likely to interact with a database that supports transactions: no big change here, except you’re likely to create the transaction explicitly yourself (unless your service runs in an EJB container or another environment that handles the transaction creation for you). The same is true if you interact with more than one resource.

Things start to differ once you combine (or compose, if you prefer) transactions into a larger unit. In a Web services environment, there is at least an option to make things behave similarly to what people are used to from 2PC scenarios as supported e.g. in a Java EE environment: WS-Atomic Transaction (WS-AT), which is part of the WS-Coordination family of standards. Essentially, WS-AT implements something very similar or equal to the 2PC protocol specified by XA. This means that your transaction context will be propagated using SOAP headers, and your implementation will take care of ensuring the resource managers hook into an existing transaction. Essentially, the same model in EJB developer is used to — your distributed transaction behaves just as atomically as a local one.

There are lots of things to say about, or rather against, atomic transactions in an SOA environment:

• Loose coupling and transactions, especially those of the ACID variety, simply don’t match. The very fact that you are co-ordinating a commit across multiple independent systems creates a pretty tight coupling between them.
• Being able to do this co-ordination requires central control over all of the services — it’s very unlikely, probably impossible to run a 2PC transaction across company boundaries
• The infrastructure required to support this is usually quite expensive and complicated.

For the most part, the need for ACID transactions in a SOA or REST environment is actually a design smell — you’ve likely modeled your services or resources the wrong way. Of course, atomic transactions are just one type of transaction — there are extended transaction models that might be a better match for loosely-coupled systems. They haven’t seen much adoption yet, though — not even in the Web services camp.

### 7. REST is unreliable

It’s often pointed out that there is no equivalent to WS-ReliableMessaging for RESTful HTTP, and many conclude that because of this, it can’t be applied where reliability is an issue (which translates to pretty much every system that has any relevance in business scenarios). But very often what you want is not necessarily some infrastructure component that handles message delivery; rather, you need to know whether a message has been delivered or not.

Typically, receiving a response message — such as a simple 200 OK in case of HTTP — means that you know your communication partner has received the request. Problems occur when you don’t receive a response: You don’t know whether your request has never reached the others side, or whether it has been received (resulting in some processing) and it’s the response message that got lost.

The simplest way to ensure the request message reaches the other side is to re-send it, which is of course only possible if the receiver can handle duplicates (e.g. by ignoring them). This capability is called idempotency. HTTP guarantees that GET, PUT and DELETE are idempotent — and if your application is implemented correctly, a client can simply re-issue any of those requests if it hasn’t received a response. A POST message is not idempotent, though — at least there are no guarantees in the HTTP spec that say it is. You are left with a number of options: You can either switch to using PUT (if your semantics can be mapped to it), use a common best practice described by Joe Gregorio, or adopt any of the existing proposals that aim to standardize this (such as Mark Nottingham’s POE, Yaron Goland’s SOA-Rity, or Bill de hÓra’s HTTPLR).

Personally, I prefer the best-practice approach — i.e., turn the reliability problem into an application design aspect, but opinions on this differ quite a bit.

While any of these solutions address a good part of the reliability challenge, there is nothing — or at least, nothing that I’m aware of — that would support delivery guarantees such as in-order delivery for a sequence of HTTP requests and responses. It might be worth pointing out, though, that many existing SOAP/WSDL scenarios get by without WS-Reliable Messaging or any of its numerous predecessors, too.

### 8. No pub/sub support

REST is fundamentally based on a client-server model, and HTTP always refers to a client and a server as the endpoints of communication. A client interacts with a server by sending requests and receiving responses. In a pub/sub model, an interested party subscribes to a particular category of information and gets notified each time something new appears. How could pub/sub be supported in a RESTful HTTP environment?

We don’t have to look far to see a perfect example of this: it’s called syndication, and RSS and Atom Syndication are examples of it. A client queries for new information by issuing an HTTP against a resource that represents the collection of changes, e.g. for a particular category or time interval. This would be extremely inefficient, but isn’t, because GET is the most optimized operation on the Web. In fact, you can easily imagine that a popular weblog server would have scale up much more if it had to actively notify each subscribed client individually about each change. Notification by polling scales extremely well.

You can extend the syndication model to your application resources — e.g., offer an Atom feed for changes to customer resources, or an audit trail of bookings. In addition to being able to satisfy a basically unlimited number of subscribing applications, you can also view these feeds in a feed reader, similarly to viewing a resource’s HTML representation in your browser.

Of course, this is not a suitable answer for some scenarios. For example, soft realtime requirements might rule this option out, and another technology might be more appropriate. But in many cases, the mixture of loose coupling, scalability and notification enabled by the syndication model is an excellent fit.

### 9. No asynchronous interactions

Given HTTP’s request/response model, how can one achieve asynchronous communication? Again, we have to be aware that there are multiple things people mean when they talk about asynchronicity. Some refer to the programming model, which can be blocking or non-blocking independently of the wire interactions. This is not our concern here. But how do you deliver a request from a client (consumer) to the server (provider) where the processing might take a few hours? How does the consumer get to know the processing is done?

HTTP has a specific response code, 202 (Accepted), the meaning of which is defined as “The request has been accepted for processing, but the processing has not been completed.” This is obviously exactly what we’re looking for. Regarding the result, there are multiple options: The server can return a URI of a resource which the client can GET to access the result (although if it has been created specifically due to this request, a 201 Created would probably be better). Or the client can include a URI that it expects the server to POST the result to once it’s done.

### 10. Lack of tools

Finally, people often complain about the lack of tools available to support RESTful HTTP development. As indicated in item #2, this is not really true for the data aspect — you can use all of the data binding and other data APIs you are used to, as this is a concern that’s orthogonal to the number of methods and the means of invoking them. Regarding plain HTTP and URI support, absolutely every programming language, framework and toolkit on the planet supports them out of the box. Finally, vendors are coming up with more and more (supposedly) easier and better support for RESTful HTTP development in their frameworks, e.g. Sun with JAX-RS (JSR 311) or Microsoft with the REST support in .NET 3.5 or the ADO.NET Data Services Framework.

## Conclusion

So: Is REST, and its most common implementation, HTTP, perfect? Of course not. Nothing is perfect, definitely not for every scenario, and most of the time not even for a single scenario. I’ve completely ignored a number of very reasonable problem areas that require more complicated answers, for example message-based security, partial updates and batch processing, and I solemnly promise to address these in a future installment. I still hope I could address some of the doubts you have — and if I’ve missed the most important ones, you know what the comments are for.

Stefan Tilkov is the lead editor of InfoQ’s SOA community and co-founder, principal consultant and chief RESTafarian of Germany/Switzerland-based innoQ.

Style

## Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

• ##### Security?

by Bernd Schuller /

• ##### Re: Security?

by Bernd Schuller /

• ##### Re: Security?

by Arjen Poutsma /

• ##### Re: Security?

by Jean-Jacques Dubray /

• ##### Re: Security?

by Ian Hlavats /

• ##### Re: Security?

by Jean-Jacques Dubray /

• ##### Re: Security?

by Ian Hlavats /

• ##### Re: Security?

by Jens Goldhammer /

• ##### Re: Security?

by Rolf Rander Næss /

• ##### Resource transformations

by Bruno Luiz Pereira da Silva /

• ##### Thanks for the sharing

by Yuen Chi Lian /

• ##### Nice.

by Zubin Wadia /

• ##### Religious Issue?

by Victor Volle /

• ##### Re: Religious Issue?

by Stefan Tilkov /

• ##### Re: Religious Issue?

by Victor Volle /

• ##### Re: Religious Issue?

by Stefan Tilkov /

• ##### Re: Religious Issue?

by Roshan Shrestha /

• ##### Re: Religious Issue?

by Daniel Yokomizo /

• ##### Re: Religious Issue?

by Victor Volle /

• ##### Re: Religious Issue?

by shruti chinni /

• ##### Re: Religious Issue?

by Sean Sullivan /

• ##### Re: Religious Issue?

by Stefan Tilkov /

• ##### Re: Religious Issue?

by Hasko Heinecke /

• ##### Re: Religious Issue?

by Hasko Heinecke /

• ##### Silver Bullet

by Daniel Joseph /

• ##### Great article

by Bill Burke /

• ##### +1 to REST

by Renat Zubairov /

• ##### Towards Greater Clarity

by Dan Creswell /

• ##### Re: Towards Greater Clarity

by Stefan Tilkov /

• ##### Re: Towards Greater Clarity

by Bill Burke /

• ##### Protocol independence

by Marc de Graauw /

• ##### My answers to 5 of these doubts

by Ganesh Prasad /

by J Hwang /

• ##### Good points

by Arun Batchu /

• ##### Re: Good points

by Arun Batchu /

• ##### Some problematic cases

by Mark Kron /

• ##### Security

by Shivendra Dubey /

• ##### +1 for self documenting resources

by Juergen Brendel /

• ##### Security?

Your message is awaiting moderation. Thank you for participating in the discussion.

In the WS-* space a lot of options are available for building secure applications. How to realise message encryption, signing, trust delegation etc in a pure REST way?

• ##### Re: Security?

Your message is awaiting moderation. Thank you for participating in the discussion.

should read the conclusion as well before commenting :-)

• ##### Re: Security?

Your message is awaiting moderation. Thank you for participating in the discussion.

When using XML payloads, the same standards that make up WS-Security (XML-DSIG and XML-Enc) are still available to you.

• ##### Re: Security?

Your message is awaiting moderation. Thank you for participating in the discussion.

Arjen:

don't you need an "envelope" mechanism to be able to convey the tokens? Security is not just about encryption and signature, authentication, authorization, user identity propagation are difficult to achieve without an envelope.

• ##### Resource transformations

Your message is awaiting moderation. Thank you for participating in the discussion.

Something I'd like to see more discussions is Resource Transformations. When you're developing RESTFul services that go somewhat beyond CRUD, you might have several resource transformations.

When a given resouce changes to or from some state, there might be transformations on other resources. For example, let's think of some Amazon sales process where you have Item and Order resources and several related resources like billing and logistics stuff. When the user pays for the Order, some transformation in billing resources would apply a transformation to the Order resource, changing its state to "paid"

When the Order resource has its state changed to "paid", we could have transformations applied to logistics resources, telling the delivery system to deliver the order.

This kind of resource transformations appear a lot when you're developing RESTFul services that are more than CRUD. I think a very good approach to solve this is using finite state machines, defining what resource states we have and what happens in every meaningful state transition.

I'd like to see more discussion about this kind of things, because resource transformations might be very tricky, and complex RESTFul services definitely need them.

• ##### Re: Security?

by Ian Hlavats /

Your message is awaiting moderation. Thank you for participating in the discussion.

Arjen:

don't you need an "envelope" mechanism to be able to convey the tokens? Security is not just about encryption and signature, authentication, authorization, user identity propagation are difficult to achieve without an envelope.

HTTP provides the envelope mechanism. It defines authorization/authentication headers and status codes for this purpose. Cookies can be used to propagate user identity tokens.

• ##### Re: Security?

Your message is awaiting moderation. Thank you for participating in the discussion.

Ian:

sorry, I thought the question was WS-Security. I did not know that the HTTP envelope was compatible with WS-Security nor supported as many different authentication mechanisms, let alone trust federation.

• ##### Re: Security?

Your message is awaiting moderation. Thank you for participating in the discussion.

The problem is that you have to implement all this kind of stuff for your own. In Axis2 you can activate it by writing a few lines of code...

• ##### Re: Security?

by Ian Hlavats /

Your message is awaiting moderation. Thank you for participating in the discussion.

Ian:

sorry, I thought the question was WS-Security. I did not know that the HTTP envelope was compatible with WS-Security nor supported as many different authentication mechanisms, let alone trust federation.

You are correct Jean-Jacques. HTTP security is not as sophisticated as WS-Security, but its basic features (encryption, certificates, authentication, authorization, etc.) could still meet the security needs of some systems.

Plus, HTTP security is extensible:

The HTTP protocol does not restrict applications to this simple challenge-response mechanism for access authentication. Additional mechanisms MAY be used, such as encryption at the transport level or via message encapsulation, and with additional header fields specifying authentication information. However, these additional mechanisms are not defined by this specification. (HTTP specification)

It would be interesting to see the WS-Security stickers ported to HTTP headers (as suggested by Richardson and Ruby in the RESTful Web Services book).

• ##### Thanks for the sharing

Your message is awaiting moderation. Thank you for participating in the discussion.

Agreed. Nothing is perfect for every or even a single scenario.

At least, this article points out that there's always a workaround to a limitation. It's up to how you explore within a given scope.

- yc

• ##### Nice.

by Zubin Wadia /

Your message is awaiting moderation. Thank you for participating in the discussion.

The Amazon approach is interesting:

docs.amazonwebservices.com/AmazonS3/2006-03-01/...

Cheers,

CTO
www.imagework.com
"Business Acceleration through Process Automation."

• ##### Religious Issue?

by Victor Volle /

Your message is awaiting moderation. Thank you for participating in the discussion.

The REST vs. WS debate is now taking some years. This seems strange.
So perhaps instead of putting forward (mostly) the same (refined) arguments
again and again, we should ask ourselves: why? If two parties are disputing
for a long time, they either have completely different viewpoints with
regard to some central _values_ or they simply misunderstand each other.

I think, both is the case. And I think the central issue is API design.
Do you think more about things or what you can do with these things -- i.e. things or verbs.
That's it. That's it? Let me try to explain.

If you come from a business process view, or from a library design view, you
probably are used to think APIs should contain methods like

 (a) updatePerson() (b) retrievePerson() (c) findPerson()

but this kind of CRUD methods, you could quite simply map to their RESTful equivalents.

 (d) scoreCustomerMortgageRisk(customerId)      // i.e. the customer has send in a mortgage application,      // that should now be "scored" to decide if we can offer      // him a credit contract (e) promoteToCustomer(personId)     // a person that is in our system, will now become a      // customer (an account will be opend, etc.) (f) calculateNetInterestRate(credit)

No doubt, you can map these to some RESTful services. (e) might be a PUT (or is it a POST?) of the
Person to a CustomerCollection-Resource (Thanks to Stefan Tilkov, for explaining this to me quite some time ago). And sure in both cases you need a human readable documentation.

But what is more natural to you? If you say "promotePersonToCustomer" you would probably prefer
the WS-Stack and if you think a simple PUT of a Resource is more natural and web-like, you probably
prefer RESTful services.

But please, please do not try to convince me that WS are an abuse of HTTP. If it helps me to achieve
a business goal with less effort (in the long run) then, please, let me use whatever I like.
If using my nose to press keys on my keyboard works faster for me, so why not?
"Abusing" sounds so childish, like I am playing a game with your toy that you never thought of before.

And the WS folks: please do not try to convince me that WSDL and XML-Schema are a good idea.
WSDL is a mess and XML-Schema ain't much better.

And some REST proponents seem to insist that

   foobar/promoteToCustomer/{personId}

is so much better (web-like, or whatever) than

   promoteToCustomer(personId)

Less coupling? More interface stability?
Because of the indirection that forces me to map this URL to a method invocation?
Sorry, I don't get it. Whether I do the indirection by mapping the URL to a method, or
I change the method implementation to call another method ... what's the difference?

The only are where REST has an advantage is interface versioning. Because there is no
coupling of XML to a Schema, I can much easier add elements and attributes to my
XML responses than with XML Schema. But if I rename, remove or otherwise alter my XML,
I have the same problems as with XML Schema. Perhaps even more so as long as I do
not have a (formal) description of my XML that I could easily compare between to versions.

So my conclusion is: Use whatever helps you to achieve your goals. And if your developers
are more accustomed to one or the other, that should influence your decision to some degree.
If your services are only used inside your company, if your servcies just wrap an existing API,
you probably shouldn't use REST. If you are a big company, that offers services over the web
and you want to attract many people to use your services (include them in their own applications,
mash-ups, etc.) REST is often much simpler to use.

But don't believe either side, if they are telling you: theirs is the only way (sounds much
preachy to me).

• ##### Re: Religious Issue?

Your message is awaiting moderation. Thank you for participating in the discussion.

Victor, would you consider using a RDBMS and then defining a single table only, with two columns, "id" and "content" (the latter a BLOB) an abuse of the RDB?

• ##### Re: Religious Issue?

by Victor Volle /

Your message is awaiting moderation. Thank you for participating in the discussion.

:-)

yes, I would (but I have seen a system, where the RDB was only used as a Cache for some mainframe using only key-value-pairs as data structure -- and they were so proud that they were now using a DB).

But I am not sure that your analogy really fits. An RDB seems to be much more complicated than HTTP to me. But, okay "Übertreibung macht anschaulich" (hyperbole makes colorful).

When I am using HTTP for REST, I am retrieving and sending "Resources" (and deleting them, and yes there are arcane differences between PUT and POST) and have some standard status responses (400). These Resources have some structure, HTTP knows nothing about.

When I am using WS over HTTP, I am sending documents, that have a structure, HTTP Knows nothing about. And I am super imposing some semantics, HTTP knows nothing about, but with

   PUT foobar/customerCollection/{partnerId}

I am still imposing the same semantics (I probably have to update some mainframe system as well). So what's the big difference.

Claiming I shouldn't abuse HTTP sounds like the Gospel according to REST.

But I think that "abusing" HTTP is only a side issue in the REST vs. WS debate.

PS: why is there all the whitespace at the end of my postings?

• ##### Silver Bullet

Your message is awaiting moderation. Thank you for participating in the discussion.

Yes. Finally we have the silver bullet. In other words, if you find anything that can not be implemented elegantly in REST, you have a problem in your design/architecture.

• ##### Re: Religious Issue?

Your message is awaiting moderation. Thank you for participating in the discussion.

I don't think there's anything religious about the "abuse" argument. HTTP was designed as an application protocol with particular strengths (and of course, weaknesses). Using only 5% of it - i.e., just POST, a small numer of URIs to identify "endpoints", and only two response codes - dumbs it down drastically and degrades its role to that of the underlying transport (TCP).

Regarding the RDB analogy: just like you can't meaningfully use SQL in the example above (and thus defeat the RDB's purpose), you can't use hypermedia or caching when using WS-* and HTTP. Seems very similar to me.

Does it merit the word "abuse"? Who knows. It's just words.

• ##### Great article

by Bill Burke /

Your message is awaiting moderation. Thank you for participating in the discussion.

Stefan, these two articles are a must read for any REST noob. Thank you for articulating so well the points I fumble to try to explain to others when evangelizing REST.

On transactions, I have similar fears that distributed transactions and loose coupling don't mix. It was enough hard to get this stuff to work in a CORBA environment because of different vendor spec interpretations and lack of interoperability certifications. I can imagine it is even worse in the WS-* specs which are generally moving targets. I wrote down some thoughts on redefining the problem and solution awhile back. I always thought that these large b2b transactions needed to be modeled rather than abstracted away by specifications like WS-BA.

I also loved this quote from your article: "Trying to dumb widely different options down to their least common denominator serves no-one. An analogy would be to create a common abstraction that hides a relational database and a file system under a common API. Of course this is doable, but as soon as you address aspects such as querying, the abstraction turns into a problem."

I'm hoping this is a stab at the JDO crowd :)

Regards,

Bill

--
Bill Burke
JBoss, a division of Red Hat
bill.burkecentral.com
resteasy.sf.net

• ##### +1 to REST

Your message is awaiting moderation. Thank you for participating in the discussion.

Very nice article indeed. Especially I liked the Atom/RSS ideas for pub/sub. Really interesting. Will definitely try out.

• ##### Re: Religious Issue?

Your message is awaiting moderation. Thank you for participating in the discussion.

but this kind of CRUD methods, you could quite simply map to their RESTful equivalents.
 (d) scoreCustomerMortgageRisk(customerId)      // i.e. the customer has send in a mortgage application,      // that should now be "scored" to decide if we can offer      // him a credit contract (e) promoteToCustomer(personId)     // a person that is in our system, will now become a      // customer (an account will be opend, etc.) (f) calculateNetInterestRate(credit)

I'm a REST proponent, but I also understand that it is <em>a</em> architectural style so your app may have different constraints and that's fine. Now looking at your examples I would ask the following questions: (d) How do we get feedback about this process? Is it synchronous or asynchronous? Do we talk about the scoring process itself? As an answer to those questions I would model it as a subordinate resource under the mortgage application so we can just PUT /mortage-application/{id}/score. Likewise we should be able to see if the score is done by issuing a GET. (e) What happens if a promotion fails? Do we keep track of who was promoted? As with (d) in most organizations people talk about promotions as objects with its own attributes (e.g. date of promotion, reason, who made the sale) so I would see no problem in POST /people/{id}/promotions resulting in a 303 with Location: /customers/{id} (it's important to remember that a resource may be acessible via multiple URIs so it's entirely possible to an action in an URI cause effects in other URIs). (f) seems to be a simple calculation process, I can't immediatly identify a resource associated with it, other than a calculator (which may be a proper resource in some cases but in this one it just smells like a RPC in disguise), I would have no problems with having it be a regular SOAP based WS, but I would try to understand the domain better to see if there's a natural resource attached to the calculation.

• ##### Re: Religious Issue?

Your message is awaiting moderation. Thank you for participating in the discussion.

 (d) scoreCustomerMortgageRisk(customerId)      // i.e. the customer has send in a mortgage application,      // that should now be "scored" to decide if we can offer      // him a credit contract (e) promoteToCustomer(personId)     // a person that is in our system, will now become a      // customer (an account will be opend, etc.) (f) calculateNetInterestRate(credit)

There is a similar discussion in IBM's article "Resource-oriented vs. activity-oriented Web services"

www.ibm.com/developerworks/xml/library/ws-restv...

• ##### Towards Greater Clarity

by Dan Creswell /

Your message is awaiting moderation. Thank you for participating in the discussion.

Hi Stefan,

I am somewhat torn over this article. Some of it I like a lot, some of it feels a little wide of the mark. What follows are notes/questions which I hope we can use to lever out some further clarification....

On (2) - the schema information you mention describes the format of the data exchanges but it's missing an expression of the endpoints at which the interaction takes place. Of course this stuff lives in the HTML you mention later however this is not a "standard".

WSDL by contrast contains all this information in one place and in turn lends itself to stub/skeleton generation and that's what many developers find appealing.

Which option one prefers is determined by the desire for greater automation or a desire to engage in some thought, dig through some documentation etc.

On (4) - I don't think you've actually addressed the doubt here. REST itself is an abstraction and it's often put over the top of data and operations implemented in the usual three-tier style. i.e. The usual systems architecture hidden behind a Web "facade".

"Depending on a widely accepted, officially standardized protocol such as HTTP is not really a problem" - widely accepted is not the same as widely used and there are systems out there that need integrating that don't do http. These systems are often hidden behind firewalls away from the Web and are important to "enterprise" programmers whilst being almost invisible to many "web" programmers.

I think the real issue that needs surfacing here is can one do REST without http?

On (5) - An observation:

If one is designing with WS-* be it for Web Services or othewise, we're following patterns (rightly or wrongly) that have been evolved via CORBA, EJB and so on in our designs. i.e. There's a lot of history that people are used to and immersed in.

REST in contrast does not have such a widely communicated and agreed set of patterns yet. Sure there are a number of people programming on the Web but do they think Web or do they think Enterprise? I suspect that those thinking Enterprise are in the majority.

I'm not sure the leap on into SOA helps you here. One doesn't need to be doing SOA at all to be building a Web Service with WS-*. In fact SOA for most people is merely technology driven architecture and thus they are simply following their normal implementation patterns. They aren't thinking at architecture level as one might (but doesn't have to) do with REST.

And that's the nub of the issue - if one thinks in terms of architecture one agrees on patterns etc, if one get's lost in the technology it's all about religious biases and there will be little agreement. Think you're better off steering clear of that....

At the end of the day I view SOA (and REST as well) as one means of doing what good architecture is all about. Splitting up your system into small manageable pieces and exposing them in an appropriate fashion via http or CORBA or Messaging or RMI or whatever. However I suspect that most don't share this view.

On (6) - REST has little to say explicitly about transactions whilst the WS-* specs and SOA bigots do. That's a problem if one views the world transactionally or needs a transaction.

ACID may or may not be desirable within a system, sometimes one needs it, sometimes one doesn't. By preference we should strive to avoid it because it's a scalability/availability inhibitor. However in some cases it is necessary and the fact that REST says little will cause people to veer toward WS-*.

We must not forget that ACID amongst other things determines how an observer sees updates manifest. If we can stand them to be eventually consistent, distributed transactions aren't required. Sure one can attempt to bundle all information affected by a distributed transaction together (and remove the need for a transaction) but that can lead to large unwieldy chunks of information which is a bad design smell in itself.

On (7) - WS-Reliable Messaging is yet another example of centralized solutions to reliability which are generally believed to solve all reliability problems. They don't of course but the perception they do manifests as a requirement on REST.

The only way to achieve total reliability is for every single point in a system to maintain sufficient persistent state that it can remember what is was doing and recover as necessary (that would include the human being driving the application, if any). Many people equate message brokers with being the way to do reliable. They've failed to realize that a message is only durable/reliable once it's replicated on disk or in the memory of a number of machines in a cluster. i.e. If the client has no persistent storage and fails half way through transmitting a message to a broker for "reliable messaging" the message is lost forever unless there's something that remembers to resubmit.

A further issue is that whilst these reliable brokers will eventually deliver a message they don't necessarily provide any consideration of timeliness of delivery which can be troublesome under various circumstances.

On (8) - The whole pub/sub, pull/push thing has been done before:

fuzzypanic.blogspot.com/2007/08/pubsub-vs-atom....

Polling is an efficient way to scale for data that is changing slowly and viewed by a large number of clients. Polling doesn't always work so well for highly volatile data. I would venture to suggest that one would need to be looking at other messaging solutions for this be they traditional brokers or AMQP/XMPP implementations.

On (9) - You may have meant this when discussing the option for a client to pass a URI - Many people when dealing in asynchronous processing also want an event delivered to the client to identify when it's completed as opposed to the polling model you apparently suggest.

• ##### Protocol independence

Your message is awaiting moderation. Thank you for participating in the discussion.

Another counter-argument to the 'protocol independence' argument: it is mostly mentioned when support for legacy is required (message goes over HTTP, then JMS, then MSMQ etc...): but legacy typically does not support the WS-* stack either. So you'll either have to build a gateway or update the entire legacy chain anyway.

• ##### Re: Towards Greater Clarity

Your message is awaiting moderation. Thank you for participating in the discussion.

Hi Dan, thanks for the detailed remarks. Let me try to address some of them:

With regards to (2), schema being the most relevant part of WSDL, I know many developers love having the code that handles XML to be generated for them. While I'm not among them, I understand the desire -- and tools to do this are available when working with REST, too.

You are right that if you want to have code generated for more than the data part, WSDL has the metadata that allows you to do so. In practice, I consider this too be much less of a concern.

Regarding (4), protocol independence, my main intent was to say that if I have the choice to standardize a) on HTTP or b) on Web services, I consider option a) to be the one that's far more widespread and supported than b). Therefore, I don't consider hiding HTTP below a layer of abstraction a goal worth pursuing. There may be a lot of situations, of course, where HTTP is bad choice, and something else might make more sense. That's fine, too; just use it, but don't try to turn HTTP and, say, AMQP into the same thing by adding a layer on top (because they aren't the same thing at all).

I can agree with most of what you observe regarding (5). I still claim that two people tasked with solving a problem using RESTful HTTP will arrive at a solution far more similar than two people doing so with WS-*, CORBA, EJB or DCOM.

I agree on (6).

Similar, no disagreement on (7).

On (8), I think we agree that polling doesn't always work, and other solutions may be better for a significant number of use cases. I can't comment on the XMPP/AMQP combination for lack of experience, but it seems one worth considering.

Regarding (9): Yes.

Stefan

• ##### Re: Religious Issue?

Your message is awaiting moderation. Thank you for participating in the discussion.

Quoting from James Snell's article:

To offer a contrast, compare this with a recent proof-of-concept project IBM implemented to illustrate the use of Web services to automate hospital patient records access, prescription writing, operation scheduling, and so forth. Without going into any details (which are covered by a non-disclosure agreement with the client), the primary focus of the collection of service interfaces created for the system focused strictly on activities that users could perform in the system. For example, scheduling a procedure or a test for a patient and requesting asynchronous notification of such events as availability of test results. While patient records (resources) are an important aspect of the system, they generally serve a supporting role in the overall application and are not the central focus of the system. Rather, the hospital prototype is an activity-oriented service, which is accurately reflected by it's SOAP-style Web service architecture.

I'm pretty sure James, who is the driving force between the AtomPub implementation Abdera, would view things differently now. This particular use case, IMO, is a great example of something that could be mapped to a RESTful without much difficulty, yielding a lot of benefits -- such as being able to link to individual results, producing feeds for changes, linking to images ...

• ##### Re: Towards Greater Clarity

by Bill Burke /

Your message is awaiting moderation. Thank you for participating in the discussion.

On (9) - You may have meant this when discussing the option for a client to pass a URI - Many people when dealing in asynchronous processing also want an event delivered to the client to identify when it's completed as opposed to the polling model you apparently suggest.

Imagine how much simpler and portable this would be if modeled in a RESTful way? If the protocol was HTTP, the message producer could just append a custom "reply-to" header with the URI of the reply-to queue. The consumer of the message sees the header and just does a POST to it.

I do agree that some REST over HTTP standards should be put in place for doing things like transactions and messaging. I imagine they would be a lot simpler and easier to implement :)

I think another thing to consider is why is REST gaining in popularity? Once you start researching this you start to see why a lot of distributed computing veterans are finding the model so appealing over WS-*.

• ##### My answers to 5 of these doubts

Your message is awaiting moderation. Thank you for participating in the discussion.

1. REST may be usable for CRUD, but not for “real” business logic

If CRUD appears too fine-grained, remember that the definition of the "resource" can be arbitrarily coarse-grained. Creating a new Bill of Lading in a shipping application is just a PUT or POST operation as the case may be, but the accompanying XML document has sufficient richness and complexity for the operation not to be considered fine-grained.

2. There is no formal contract/no description language

I've explained why REST does not need a description language in my blog post REST Eye for the Relational Guy. In short, when the basic interaction patterns are made uniform, they become "assumed knowledge" and don't have to be explicitly described. Only application data needs to be described.

3. Who would actually want to expose so much of their application’s implementation internals?

If you're exposing domain objects directly through a RESTful interface with no service-oriented interface design, that could indeed be a problem. But REST done right provides the appropriate abstraction to decouple what the application client sees from the actual domain model being implemented. I've blogged about this property of REST as well.

7. REST is unreliable

While people often demand reliability, they will usually be satisfied with idempotence. In fact, in any distributed computing environment, end-to-end reliability is a chimera anyway, as illustrated by The Two-Army Problem. REST is perfectly capable of supporting idempotence through design patterns such as the proposed standard "POST-Once-Exactly". It's trivial to implement this design pattern within your application's logic, even if the proposed HTTP-related standard doesn't materialise in your project's timeframes. Investing in six-figure reliable queueing infrastructure still doesn't solve the problem of end-to-end (i.e., application-to-application) reliability.

10. Lack of tools

If you have the tools to build conventional web applications, you already have most of the tools required to build RESTful applications. The only additional tools you may need relate to XML definition and processing. All of these are stock-standard and readily available.

Regards,

• ##### Example REST interface in an enterprise product

by J Hwang /

Your message is awaiting moderation. Thank you for participating in the discussion.

Splunk's latest version uses REST with Atom syndication to power its backend. It's a marked improvement over SOAP, our previous interface, and definitely makes interacting with the product far easier. Our integration partners are definitely much happier with it as well. I have a blog post that elaborates on our design decisions: dev.splunk.com/2008/03/06/using-the-atom-feed-f...

• ##### Re: Religious Issue?

Your message is awaiting moderation. Thank you for participating in the discussion.

Off tpoic, but regarding a generic database model, there is the Entity Attribute Value (EAV) model that has seen some usage and seems appropriate for some cases ycmi.med.yale.edu/nadkarni/eav_cr_frame.htm).

• ##### Re: Religious Issue?

by Victor Volle /

Your message is awaiting moderation. Thank you for participating in the discussion.

I tried to eleborate on my comment a little bit more thoroughly: victorvolle.wordpress.com/2008/03/31/rest-vs-ws...

• ##### Re: Security?

Your message is awaiting moderation. Thank you for participating in the discussion.

If you want to add security on the message-level, using existing XML-standards, this is true, you must implement it specifically for your REST-app. However, the point of REST is to leverage HTTP, which already has mechanisms for encryption, password authentication and one- or two-way pki-authentication. All available through configuration in your web-server, no need for programming.

• ##### Good points

by Arun Batchu /

Your message is awaiting moderation. Thank you for participating in the discussion.

All good points Stefan.
> Lack of tools
Tools everywhere! The browser becomes your IDE; Or your <favorite programming language> IDE; or XML IDE or XQuery tool
> Transactions
The RestFul book has a very interesting take on how to do transactions in a RESTful way. I like it (not used it though).
BASE vs. ACID properties is an interesting way to reconcile transactions. You touch upon the scaling issues of 2PC protocols. Just can't do it.

</favorite>

• ##### Re: Good points

by Arun Batchu /

Your message is awaiting moderation. Thank you for participating in the discussion.

Apparently, I cannot put angle brackets - my fault.
I meant to convey that your favorite programming language IDE and any tool that can handle a URI/URL (hence the browser) becomes a tool to test and write your RESTful services.

• ##### Re: Religious Issue?

Your message is awaiting moderation. Thank you for participating in the discussion.

Hi Daniel Yokomizo,

I have been searching for some explanation for complex business logic handling in REST. Your post does clarify how we should modify our viewpoint with respect to the complex business logic. But now my question is that is the utility that we gain out of this "complex" viewpoint of the application process worth the effort, when it can be replaced by service-oriented approach. One of the arguments was that SOA requires the knowledge of the web service for it being used. But doesnt that apply for REST too.

We need to know the process, in the very least, in order to call the "correct" URI? How loosely coupled is this as compared to the SOA version?

• ##### Some problematic cases

by Mark Kron /

Your message is awaiting moderation. Thank you for participating in the discussion.

Hi

Relating to point 5, I'd like to share with you some problematic cases. I like the REST idea that for actions (verbs) you use standard set of protocol methods and URLs identify things (nouns). These are example cases which I was not able to easily fit into this picture:

1. Application has two lists of similar things: A and B (say identified as /app/A/<some id> and /app/B/<some id>). In the interface I want to expose an action that means "change given A to became a B" (or "move given thing from list of A to list of B").

2. Application has list of things of type A. In the interface I want to expose two separate views for A, not differing by the returned media (html, xml, pdf etc.) but by the data set, say: basic view and detailed view.

3. Application has list of things of type A. In the interface I want to expose a custom operation on a selected item, which is not simple update with data that comes from a client, but from the server, and client only triggers the operation. Say: "refresh A" or "reset A".

What are your proposals of REST interface for these?

Kind regards
Mariusz
</some></some>

• ##### Security

Your message is awaiting moderation. Thank you for participating in the discussion.

I have seen comments for security with REST. But i am not sure how are we going to protect data which is passed in URL (in case of using HTTP GET). The URL is going to go over the internet and can be hacked anytime.

• ##### +1 for self documenting resources

Your message is awaiting moderation. Thank you for participating in the discussion.

Hi Stefan,

I like your comment about the self documenting resources. That's exactly right: You still need a human readable documentation. If your resources are discoverable (follow links) you have a very nice system in place, which allows people and even search engines to find the resources you can offer.

We did that for RESTx, where each component (pieces of code that act as the basis for resources) and each resource (particular configurations for that component) are discoverable and show a human readable description.

If you are interested, you can see how you can take a tour of the RESTx server, just with a web browser.

• ##### Re: Religious Issue?

Your message is awaiting moderation. Thank you for participating in the discussion.

Hi Victor, long time no see :)

I agree with your sentiment, there is not just one true way.

However, to address the three very good examples you brought up, consider this:

scoreCustomerMortgageRisk(customerId)

Actually, here the client making implementation assumptions about the backend. Indeed, the risk score is a property of the mortgage application. The client wants to know the risk score? Go ask for it.

GET .../mortgageApplication/{id}/riskScore

Or perhaps the risk score is really just a property in the mortgage application entity itself. (I'm talking about the application like the form you fill out, not the IT kind off application consisting of lines of code, just to clarify.)

In your SOAPy example, you are telling the backend to actually calculate it. Maybe someone already calculated it. Maybe calculation will take overnight until the risk cube is recalculated. Don't tell the backend what it should do, tell it what you want to *know*.

In that sense, the RESTful alternative has less coupling: It doesn't make assumptions about when a risk score needs to be calculated. It delegates this decision to the backend, as it should.

Your third example is just the same. Again, ask what you want to know (the net interest rate) and don't tell the backend what to do (calculate the rate). Let the backend do its job. That's how coupling is reduced.

Your middle example is also interesting. There are different RESTful strategies here. One could argue that you should just GET the client, adding the prospect's uri (or an id) as a parameter. Then the server should see that the client doesn't exist and promotes it if possible, returning the ready made client.

However, I think in this case the failure modes are too complex. Promoting a prospect to customer could return in various states. It could fail because preconditions aren't met. It could semi-complete, lingering in an intermediate state because, say, there's a second signature missing. It could succeed but you're not allowed to access the customer because they're assigned to somebody else. Whatever, I believe it's not a good idea to whop that all together in a single GET request that is intended to retrieve existing customers.

So I'd argue you need to create a request entitiy for promoting the prospect to customer.

CREATE .../prospectPromotionRequest/{prospectId}

This request can then be GET-ed to check its completion status and any complex failure modes. It might not even result in a new customer at all but rather a workflow task entity or whatever.

The idea to turn an operation into a request for performing the operation may seem very German (or Byzantine) but in fact that's how a lot of batch processing in financial institutions already work. It lends itself also quite nicely to the documentation requirements of today's equally byzantine regulatory environments. So while this may not reduce coupling as compared to the original soapy operation, it has other beneficial features.

So yeah, it's not always easy to come up with a good RESTful design and I'm not saying mine is the One True Way. But once you get in the RESTful headspace, there's sometimes surprisingly good solutions that go beyond just WS vs. REST.

• ##### Re: Religious Issue?

Your message is awaiting moderation. Thank you for participating in the discussion.

... and yes, I know that it's POST and not CREATE. ;)

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Is your profile up-to-date? Please take a moment to review and update.

Note: If updating/changing your email, a validation request will be sent

Company name:
Company role:
Company size:
Country/Zone:
State/Province/Region:
You will be sent an email to validate the new email address. This pop-up will close itself in a few moments.