129

I'm going to learn RESTful web services (it's better to say that I'll have to do this because it's a part of CS master degree program).

I've read some info in Wikipedia and I've also read an article about REST at Sun Developer Network and I see that it's not easy technology, there are special frameworks for building RESTful apps, and it's often being compared to SOAP web services and programmer should understand when to use SOAP and when REST could be nice approach.

I remember that several years ago SOAP was very popular (fashionable?) and item 'SOAP' had to be present in every good CV. But in practice it was used very rarely and for achieving very simple purposes.

It seems to me that REST is another 'last word of fashion' (or I can be totally wrong because I haven't ever seen REST in practice).

Can you give me some examples were REST should be used and why we can't do the same without REST (or why we should spend much more time to do the same without REST)?

UPD: Unfortunatelly I can't see any concrete arguments which can blow my mind in first comments. Make me think that REST is awesome technology!

I'd like to see answers like this:

I was developing another complex HelloWorld application and we need to transfer lots of / tiny data and I proposed REST solution to my workmate:

– Oh, damn! Jonny, we should certainly use REST for implementing this app!
– Yes, Billy, we can use REST, but we would better use SOAP. Trust me 'cause I know something about developing HelloWorld applications.
– But SOAP is old-fashioned technology from the last century and we can use better one.
– Billy, are you ready to spent 3 days for experimenting with REST? We can do this with SOAP in 2 hours..
– Yes, I'm sure that we'll spent even more time to achieve the same security/performance/ /scalability/whatever else with SOAP. I'm sure that HelloWorld applications should be developed only with REST from now.

Slava Babin
  • 708
  • 2
  • 12
  • 30
Roman
  • 64,384
  • 92
  • 238
  • 332
  • 3
    It's not an awesome technology - it's a different technology. If you want someone to convince you it is awesome and should be used every time, try a consultant. – quillbreaker Sep 03 '09 at 15:27

8 Answers8

137

REST should be used if it is very important for you to minimize the coupling between client and server components in a distributed application.

This may be the case if your server is going to be used by many different clients that you do not have control over. It may also be the case if you want to be able to update the server regularly without needing to update the client software.

I can assure you that achieving this low level of coupling is not easy to do. It is critical to follow all of the constraints of REST to succeed. Maintaining a purely stateless connection is difficult. Picking the right media-types and squeezing your data into the formats is tricky. Creating your own media types can be even harder.

Adapting rich server behaviour into the uniform HTTP interface can be confusing and at times appears pedantic in comparison to the relatively straightforward RPC approach.

Despite the difficulties, the benefits are that you have a service that a client developer should be able to easily understand due to the consistent use of the HTTP protocol. The service should be easily discoverable due to hypermedia and the client should be extremely resilient to changes on the server.

The benefits of hypermedia and the avoidance of session state makes load balancing simple and service partitioning feasible. The strict conformance to HTTP rules make the availability of tools like debuggers and caching proxies wonderful thing.

Update

It seems to me that REST is another 'last word of fashion' (or I can be totally wrong because I haven't ever seen REST in practice).

I think REST has become fashionable because people attempting to do SOA type projects have found that using the SOAP stack they are not realizing the benefits that were promised. People keep turning back to the web as an example of simple integration methodologies. Unfortunately, I think people underestimate the amount of planning and foresight that went into creating the web and they oversimplify what needs to be done to allow the kind of serendipitous reuse that does occur on the web.

You say that you have never seen REST in practice, but that cannot possibly be true if you ever use a web browser. The web browser is a REST client.

  • Why do you not need to do a browser update when someone changes some html on a web site?
  • Why can I add a complete new set of pages to a web site and the "client" can still access those new pages without an update?
  • Why do I not need to provide a "service-description-language" to the web browser to tell it when it goes to http://example.org/images/cat that the return type will be a jpeg image and when you go to http://example.org/description/cat the return type will be text/html?
  • Why can I use a web browser to visit sites that did not exist when the browser was released? How can the client know about these sites?

These may sound like inane questions, but if you know the answer, then you can start to see what REST is all about. Look at StackOverflow for more benefits of REST. When I am looking at a question, I can bookmark that page or send the url to a friend and he can see the same information. He doesn't have to navigate through the site to find that question.

StackOverflow uses a variety of OpenId services for authentication, gravatar.com for avatar images, google-analytics and Quantserve for analytical information. This kind of multi-company integration is the type of thing the SOAP world only dreams of. One of the best examples is the fact that the jQuery libraries that are used to drive the StackOverflow UI are retrieved from Google's Content Delivery Network. The fact that SO could direct the client (i.e. your web browser) to download code from a third-party site to improve performance is testament to the low coupling between web client and server.

These are examples of a REST architecture at work.

Now some web sites / applications do break the rules of REST and then the browser does not work as expected.

  • The infamous back button problem is caused by using server side session state.
  • Load balancing can become a pain when you have server side session state.
  • Flash applications often prevent the URL from specifically identifying a representation.
  • The other problem that breaks web browsers is poor conformance to media-type standards. We hear all of the time about how IE6 needs to be killed. The problem there is that standards were not properly followed, or were ignored for whatever reason.
  • The use of login sessions are the source of many security holes.

REST is everywhere. It is the part of the web that makes it work well. If you want to build distributed applications that can scale like the web, be resilient to change like the web and promote re-use as the web has done, then follow the same rules they did when building web browsers.

Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • @Darrell: how in the world does REST reduce coupling over SOAP? Or, how does SOAP increase coupling over REST? Are you referring to the fact that a SOAP client actually needs to understand SOAP, but a REST client only needs to understand the media types? – John Saunders Sep 05 '09 at 02:30
  • 4
    @John Generally the way SOAP is used causes the client to require "compiled in" knowledge of every server side endpoint, every parameter data type and every return type. There is no guidance in the SOAP world to try and use standardized types to pass data between client and server. That means that every new service a client developer goes to use, has its own unique set of types, endpoints and interaction protocol. That's coupling. – Darrel Miller Sep 05 '09 at 02:53
  • @John REST attempts to standardized the interaction protocol to the semantics of the HTTP verbs, the data formats to IANA registered types and all endpoints should be dynamically discoverable. That means the client/server coupling is localized to the definition of the media type. Just as Rich said, "your service narrows the scope of coupling to just one thing - media types." – Darrel Miller Sep 05 '09 at 02:56
  • @Darrell: that is not coupling in the traditional sense. The client may be considered to be "coupled" to metadata (the WSDL), but not to the service. Consider a service that returns an "Employee": {int id; string firstName, lastName, streetAddress1, streetAddress2, city, state; int zip;}. You seem to be suggesting either that we register "Employee" with IANA, or that we just consider "Employee" to be an associative array of name/value pairs. – John Saunders Sep 09 '09 at 06:05
  • @John Let me define what I mean by coupling in WSDL terms. Imagine being able to have a service contract that you could add methods to, remove methods and rename methods without having to recompile the client. Consider also that the client could be directed to use these new methods without recompilation. The message contract is fixed by HTTP but is extensible via headers and the data contract is the only change that could break a client, however using metadata in the message contract the server could dynamically deliver appropriate version of the data contract to the client. – Darrel Miller Sep 09 '09 at 12:08
  • @John When it comes to defining a media type for an employee, the vnd subtree of the IANA media types registry is one way to go. The other would be something like FOAF (http://en.wikipedia.org/wiki/FOAF_(software)) It depends on how important "reach" is to you. Returning application/xml and having the client dig in and pull out "/Employee/@FirstName' is coupling you want to avoid. – Darrel Miller Sep 09 '09 at 12:15
  • @Darrel: I don't have to recompile the client if I maintain the original endpoint. The client simply won't use the new endpoint until it needs to, at which point it will be recompiled anyway. I also don't see having methods that are so generic that it makes sense to "direct the client to the new methods" without changing client code and recompiling. – John Saunders Sep 09 '09 at 14:22
  • @Darrel: we may be nearing the difference in our points of view: I haven't had a client which has needed such a low degree of coupling. At worst, I've had clients that wouldn't care if a few new elements were added to Employee. In no case would `/Employee/@FirstName` have been a problem, since deserialization would have taken care of that, producing `Employee.FirstName`, which is what the client wanted. – John Saunders Sep 09 '09 at 14:25
  • @John If you don't need the loose coupling, REST is a lot of work for nothing. That's why I don't see the point in using REST for web server to application server integration. If you control both and they are deployed in the same room, what is the point. Things have improved in the WCF world, IMHO the main advantage of the DataContractSerializer over XmlSerializer is that it is an opt-in model for elements instead of opt-out. That made data contracts much more flexible than previous. In the ASMX world, if you breathed on the service contract it would invalidate the client proxy classes. – Darrel Miller Sep 09 '09 at 14:51
11

REST was kicked off, to my knowledge, by Roy Fielding's dissertation Architectural Styles and the Design of Network-based Software Architectures, which is worth a read if you haven't looked at it.

At the top of the dissertation is a quote:

Almost everybody feels at peace with nature: listening to the ocean waves against the shore, by a still lake, in a field of grass, on a windblown heath. One day, when we have learned the timeless way again, we shall feel the same about our towns, and we shall feel as much at peace in them, as we do today walking by the ocean, or stretched out in the long grass of a meadow.

— Christopher Alexander, The Timeless Way of Building (1979)

And that really does sum it up there. REST is in many ways more elegant.

SOAP is a protocol on top of HTTP, so it bypasses a lot of HTTP conventions to build new conventions in SOAP, and is in a number of ways redundant with HTTP. HTTP, however, is more than sufficient for retreiving, searching, writing, and deleting information via HTTP, and that's a lot of what REST is. Because REST is built with HTTP instead of on top of it, it also means that software that wants to integrate with it (such as a web browser) does not need to understand SOAP to do so, just HTTP, which has to be the most widely understood and integrated-with protocol in use at this point.

quillbreaker
  • 6,119
  • 3
  • 29
  • 47
  • SOAP was defined back in 1998. How many HTTP "conventions" were conventions back then? – John Saunders Sep 05 '09 at 02:30
  • According to this http://www.w3.org/Protocols/HTTP/1.0/spec.html HTTP has been in use since 1990. So what? We all know the only reason SOAP uses http was because port 80 was most likely to be open on the firewall. Microsoft was not going to make the DCOM mistake again. – Darrel Miller Sep 05 '09 at 03:05
  • 1
    "_REST is built with HTTP instead of on top of it_" +1. This entire thread is really helpful for me to understand the validity of using REST over SOAP and vice versa. – Chris22 Jul 15 '16 at 19:04
9

From here:

REST advantages:

  • Lightweight - not a lot of extra xml markup
  • Human Readable Results
  • Easy to build - no toolkits required

Also check this out:

To be fair, REST isn't the best solution for every Web service. Data that needs to be secure should not be sent as parameters in URIs. And large amounts of data, like that in detailed purchase orders, can quickly become cumbersome or even out of bounds within a URI. In these cases, SOAP is indeed a solid solution. But it's important to try REST first and resort to SOAP only when necessary. This helps keep application development simple and accessible.

  • 4
    The cons comment is not very correct. By moving a parameter from the URI into the body this is still not secure. Use SSL for security. Also, when the data in the uri could be very long you are allowed to use post and put it in the body. Most server-side languages combine the data from the URI parameters and the POST parameters, so no change on the server should be needed. – Emil Ivanov Sep 02 '09 at 14:33
  • 1
    @Emil - Keep in mind that SSL isn't always available. Some people want message based security and not transport level based security. And as far as using the body of a POST...POST is one of the verbs used to process REST requests. You can't always re-use it to fit your needs. – Justin Niessner Sep 02 '09 at 14:37
  • 1
    A big CON: no standardized "description" language like WSDL for SOAP services - every REST service might or might not be documented, and documentation quality is very different from service offering to another..... – marc_s Sep 02 '09 at 14:43
  • 3
    @Marc_s If REST is done properly there is no need for a "description language" like WSDL. The media-types used do need to be documented, but there should not exist documentation that couples end-points to media-types. – Darrel Miller Sep 02 '09 at 14:56
  • @Darrel: I'm sorry, I don't buy the "no description language" nonsense. Even if the document types are documented, they also need to be described. Additionally, some people actually like to deserialize content into objects in a programming language. In that case, it's very useful to have a machine-readable definition of what the service can send and receive, so your tool can create the corresponding classes, and serialization code. – John Saunders Sep 05 '09 at 02:28
  • Absolutely the document types need to be described. But they do not contain the definitions of the endpoints. WSDL ties the endpoint to data types. If you do that you lose the benefits of hypermedia. I realize you currently don't see the benefits of hypermedia and therefore my argument is not likely to be convincing. However, that is why Roy keeps fighting this desire for people to pick and choose bits of REST and ignore the other bits. Without hypermedia it is perfectly logical to come to the conclusion that a description language makes sense. But without hypermedia, it's not REST. – Darrel Miller Sep 05 '09 at 03:13
  • @Darrel: I've been programming web services since .NET 1.0, and have yet to feel the need for hypermedia. – John Saunders Sep 09 '09 at 14:19
8

I can safely say I have spent a lot of time to understand this as a beginner but this is the best link to start with REST from scratch! http://www.codeproject.com/Articles/21174/Everything-About-REST-Web-Services-What-and-How-Pa

Just to pull you in,

Think of what a "traditional web service" is. It is an interface with exposed "methods." Clients know the methods' name, input and output and hence can call them.

Now imagine an interface that does not expose "methods". Instead, it exposes "objects". So when a client sees this interface, all it sees is one or more "objects". "An object" has no input and output – because "it does not do anything". It is a noun, not a verb. It is "a thing", not "an action".

For example, think of a traditional web service that provides the current weather conditions if you provide it with a city. It probably has a web method like GetWeatherInfo() which takes a city as input and provides weather data as output. It is easy for you so far to understand how a client will consume this web service.

Now imagine, in the place of the above web service, there is a new one that exposes cities as objects. So, when you look at it as a client, instead of GetWeatherInfo(), you see New York, Dallas, Los Angeles, London and so on. And these cities do not have any application specific methods hanging from them - they are apparently like inert gases - they themselves do not react.

You must be thinking – well, how does that help you, as a client, to get to the weather of Dallas? We will get to that in a few moments.

If all you get from a web service is a "set of objects", obviously you need a way to "act on them". The objects themselves have no methods for you to call, so you need a set of actions that you can apply onto these objects. In other words, you need to "apply a verb to the noun". If you see an object, say, an apple, which is "a noun", you can apply "a verb" like eat, to it. But not all verbs can be applied to all nouns. Like, you can drive a car, but cannot drive a television.

Thus, if a web service exposes only objects, and you are asked – well, let us now design a few standard actions or verbs that "all clients can apply to all objects they see", ...

wp78de
  • 18,207
  • 7
  • 43
  • 71
Rajarajan Pudupatti Sundari Je
  • 2,136
  • 1
  • 13
  • 12
4

Here are some ideas:

  • REST constrains your service to use a uniform interface. You don't have to waste time daydreaming (or arguing) about all of the possibly ways your service could work - you get right to work identifying the resources in your system. Turns out to be a big job in itself, but fortunately the problems tend to be much-better defined.
  • With resources, their associations, and their representations in hand, there's really very little to do in implementing your service because many decisions have been made for you.
  • Your system will look very much like other RESTful systems; learning curves for teammates, partners, and clients will be reduced.
  • You'll have a common vocabulary to discuss design problems with other developers, and even with those less technically minded (such as customers).
  • As Darrel says, because you're using a hypertext-driven design, your service narrows the scope of coupling to just one thing - media types. This helps you as a developer because changes to your system are contained within a narrow band of contact. This helps your clients in that fewer of your changes will break their code.
  • Almost every problem you might have in implementing REST can be solved by exposing a new resource or re-thinking your resource model. This focus is, IMO, a big productivity boost.

Bottom line, REST removes many of the most time-consuming and contentious design and implementation decisions from your team's workflow. It shifts your attention from implementing your service to designing it. And it does so without piling gobbledygook onto the HTTP protocol.

Rich Apodaca
  • 28,316
  • 16
  • 103
  • 129
  • @John If I fire up VS and create a WCF project and create an interface with the [ServiceContract] attribute, I can add any method calls I like. CreateCustomer(), MakeOrder(), ConfirmOrder(), VerifyOrder(), SubmitOrder(), CheckStockAvailability(), CancelOrder() From those methods, can you tell me what sequence I should use to process an order? Can you tell me when I am allowed to call CancelOrder()? Should I check availabilty before confirming the order? Should I verify the order before checking availability? This intercface is not likely to be consistent with the one for doing payroll. – Darrel Miller Sep 05 '09 at 03:22
  • 1
    @Darrel: I don't see how REST helps solve this. Does `MakeOrder` give out URLs for `ConfirmOrder` and `CancelOrder`? Does the client not already know how to call the service, but rather needs to be data-driven? – John Saunders Sep 09 '09 at 14:28
  • 1
    @John Exactly. The client knows that ConfirmOrder url and CancelOrder url may be provided to it, but it does not know what those urls look like and will only follow them if provided. You call it data-driven, Roy calls it Hypermedia as the Engine of Application State. – Darrel Miller Feb 03 '10 at 03:27
  • @Darrel: I guess I've simply never seen any business-critical service where I want to determine what to call next based on what URL I was passed from the previous call. – John Saunders Feb 03 '10 at 04:39
  • 1
    @JohnSaunders: that's because a REST call isn't about method calls, but state transition (think state machine). In any given state, a RESTful server would specify valid state transitions and the user or user agent chooses the transitions that it wants to follow. – Lie Ryan Apr 30 '14 at 22:59
  • Again, I have never needed or wanted to do that. I have never seen a service that was about state transitions. In fact, I question your description given that we are constantly told that the web should be stateless. In any case, even now, four years later, I have _still_ not seen a service that has used URLs to decide what to do next. And, FYI, on my previous job, I was heavily using a service touted as being "REST". Content ranges for paging result sets, but no use of URLs to decide what to do next (or how to do it). – John Saunders Apr 30 '14 at 23:28
4

Most of the "pro" answers about REST seem to come from people who have never developed a SOAP web service or client using an environment which supplies appropriate tools for the task. They complain about issues that I've simply never encountered, using Visual Studio .NET and IBM's Rational Web Developer. I suppose that if you have to develop web services or clients in a scripting language, or some other language with little or no tool support, that these are valid complaints.

I also have to admit that several of the "pro" points sound like things that might actually be true - but that I've never seen an example that illustrates their value. In particular, I'd greatly appreciate it if someone would post a comment containing a link to a good example of a REST web service. This should be one that uses multiple levels of resource, possibly in a hierarchy, and which uses media types properly. Maybe if I look at a good example, I'll understand, in which case, I'll come back here and admit it.

John Saunders
  • 160,644
  • 26
  • 247
  • 397
  • The best example publicly visible example to date is the the Sun Cloud API. Here is a walkthrough http://kenai.com/projects/suncloudapis/pages/HelloCloud#Finding_Virtual_Data_Centers Just to qualify my experience with SOAP. I have built, and still support, ASMX web services using Microsoft's Web Service Software Factory from the Patterns and Practices group. I have built WCF based services using a later release of the same software factory. I have also used WCF's System.ServiceModel.Web since is was first released with the Biztalk Services SDK in May 2007. – Darrel Miller Sep 08 '09 at 23:33
  • 1
    John- one example of a rest API is the Amazon one. They have both a @SOAP and a REST API. It might be useful for you- http://docs.amazonwebservices.com/AmazonS3/latest/index.html?RESTAPI.html – RichardOD Feb 08 '10 at 20:29
3

To add a slightly prosaic spin on to the answers already given the reason we use REST services where I am is that if you know you can hand a business partner a URL and know they will receive, in return, a nicely laid out slab of XML no matter whether they're working in .Net x.x, PHP, Python, Java, Ruby or god-knows-what it severely reduces headaches.

It also means that on the non-techy end our sales people can brag about our versatile API to people without fears of looking like complete muppets.

Much apart from the technical benefits anything it's easy for a non-techy to explain, demonstrate and feel confident about is a good thing. SOAP, although just as cool for techies is far less approachable by the non-techies and therefore isn't as easy to "sell".

I tend to notice that things non-techies can get their head round tend to stick. So I doubt REST as a technique is liable to be as susceptible as SOAP to the whims of fashion.

But all the stuff about not putting anything in a REST service that should be locked down is double true if only because the technology's so easily understood by people who aren't so technically minded.

3

REST is an architecture style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines.

In many ways, the World Wide Web itself, based on HTTP, can be viewed as a REST-based architecture. RESTful applications use HTTP requests to post data (create and/or update), read data (e.g., make queries), and delete data. Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations.

REST is a lightweight alternative to mechanisms like RPC (Remote Procedure Calls) and Web Services (SOAP, WSDL, et al.). Later, we will see how much more simple REST is.

Despite being simple, REST is fully-featured; there's basically nothing you can do in Web Services that can't be done with a RESTful architecture. REST is not a "standard". There will never be a W3C recommendataion for REST, for example. And while there are REST programming frameworks, working with REST is so simple that you can often "roll your own" with standard library features in languages like Perl, Java, or C#.

Karthick Kumar
  • 1
  • 3
  • "_In many ways, the World Wide Web itself, based on HTTP, can be viewed as a REST-based architecture. RESTful applications use HTTP requests to post data (create and/or update), read data (e.g., make queries), and delete data. Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations._" This is another great practical example for me to take away from this post. Thank you. – Chris22 Jul 15 '16 at 18:57