11 ms·

What exactly is RESTful programming?

121 points by klochner 15y ago

nsxwolf 15y ago
I write RESTful services, to the best of my ability. Half the tools I use enforce or encourage it. Confession: I don't understand what the advantages are supposed to be. I want to believe it isn't just arbitrary dogma. I really do. Applications don't care about the method or protocol a web service is using. Just get the data to and from. Humans should care about how easy it is to maintain and implement the web services and anything they choose to do to make that goal a reality is good. Oh, it makes for cute looking URIs, I guess.
- pfraze 15y ago
  For me, it's just a helpful description. I know something about an API if it's RESTful, and I know what others expect from me when I say it. And practically, Backbone.js expects REST conventions from the server API, which is a (small) gain in setup time.
  - jebblue 15y ago
    >> I know something about an API if it's RESTful With SOAP, you know everything, just ask the server for its WSDL.
    - scott_w 15y ago
      I'm currently working on a project where the WSDL is broken. The Java application that constructed the WSDL was unaware it was running behind a HTTPS proxy. This led to it importing HTTP URLs that didn't actually work. The solution was to have Suds re-route specific URLs to resolve correctly. The fact that Suds is designed this way is testament to his common this problem is. Yes, you can get HTTP servers that don't respect the safety of Get, but it's a much less common issue.
      - jebblue 15y ago
        I run my Tomcat server with AXIS providing SOAP capabilities on localhost:8080 and front-end it with Apache using ProxyPass and ProxyPassReverse. My SOAP web app runs fine, my Android test client also hits it with no complaints. My Apache server can be hit with both HTTP and HTTPS which lets me use Apache to handle certificate management while I cna run any type of app server on localhost that I want. So far no issues with this scenario. I used this for a contract I was just on and it also worked fine for both the SOAP and REST clients.
- RyanMcGreal 15y ago
  Here are some benefits: * A RESTful API is discoverable. With no background knowledge, a client can do a GET request on the root URL to get a list of resources with URLS. It's easy to dive right in and quickly figure out what is available. * Developers understand HTTP. REST is essentially just HTTP, and we already understand HTTP. REST means the API developer doesn't need to waste time and energy (badly) reinventing/re-implementing what HTTP does on top of HTTP; and the client doesn't need to waste time and energy learning a bunch of ad hoc protocols. * Our tools understand HTTP. Just about every client language/framework on earth already understands HTTP. Without jumping through any extra hoops, a client working in Python or Ruby or C# or Java or JavaScript or PHP or even VBScript can execute an HTTP request on an API resource and understand the response. * REST keeps us honest. A RESTful API architecture forces the API developer to be clear about what is a resource and what methods clients can execute against each resource. This makes for a better-organized, more orthogonal API.
  - ExpiredLink 15y ago
    Experience shows that your benefits are actually myths. A 'RESTful API' is not more discoverable, understandable and 'honest' than any conventional, local or remote API.
  - jebblue 15y ago
    >> A RESTful API is discoverable So is SOAP. >> Developers understand HTTP SOAP runs on just about anything including HTTP or even SMTP. >> Our tools understand HTTP SOAP doesn't care what the clients or servers are written in or run on. >> REST keeps us honest I disgree, you can change something in a JSON packet and the client will only know it broke when it's run. With SOAP, if your client uses a compiled language then you as a developer will know first before you give it to a customer to run, you can fix it then.
    - RyanMcGreal 15y ago
      > So is SOAP. No it's not. In theory, you can just consume the WSDL and have all the methods available to you, but in practice, there are huge and unbridgeable issues with interoperability. A C# SOAP client will have trouble consuming a Java WSDL, and so on. > SOAP runs on just about anything including HTTP or even SMTP. SOAP runs on top of HTTP but merely uses HTTP as a tunnel. All the stuff that should be in HTTP - the resource, the method, the data - is inside the XML envelope. If you want to consume a SOAP web service, expect to get your hands dirty. > SOAP doesn't care what the clients or servers are written in or run on. In theory, no. In practice, interoperability is by no means a given. > you can change something in a JSON packet and the client will only know it broke when it's run. That's not really what I was talking about, but if you make a breaking API change in any system, you should have a way to do it so clients aren't caught flat-footed when their app breaks. Neither REST nor SOAP inherently solves this problem, but REST does allow for custom media types that include versioning.
- icebraining 15y ago
  Each of the constraints brings some advantages to the system. To me, the most important is the decoupling of the client from the server. I think this doesn't seem that important because we still code each client against particular API, but we could adopt true uniform APIs - by not only using the HTTP methods and following HATEOAS, but by also standardizing on data formats that are widely adopted¹ - we would be able to write much more generic clients that could work with different APIs, perhaps even with ones not considered by the developer, without wasting hours upon hours writing code against each service. ¹ No, JSON isn't a standard data format, but more a standard serialization format. You still have to manually code against each service's response types.
- funkah 15y ago
  I can appreciate making web services a lot simpler than horseshit like SOAP. If all we want to do is get data in and out, let's do it simply and without a bunch of extra ceremony. I can appreciate the notion of using concepts we've already had forever in HTTP rather than reinventing them, poorly. Beyond good common-sense things like this, REST seems to involve a lot of people yelling about whether something is or is not REST.
  - jebblue 15y ago
    How about SOAP does computational distribution and REST does data distribution and they are both needed today.
- jakejake 15y ago
  Theoretically if done correctly then your REST service can be accessed by generic REST clients that don't know about your particular service. Though generic client isn't going to know really what to do with your service. Aside from performing basic CRUD operations, a generic client would have no understanding if what any of it actually means. But, for example you can use code libraries that are designed to work with REST services in your client and not have to write as much boring "plumbing" code.
  - extension 15y ago
    Though generic client isn't going to know really what to do with your service. This is where hypermedia comes in. A rich set of standard media types allows your generic client to do useful things without knowing about any particular service.
- yesbabyyes 15y ago
  In my experience, the biggest win is that it helps me as a developer to create clean interfaces. Whereas a homerolled RPC solution would encourage me to write controllers for different paths, taking arguments in various ways, when writing a REST interface I can create some kind of object: { index: function (req, res) { ... } create: function (req, res) { ... } retrieve: function (req, res) { ... } update: function (req, res) { ... } delete: function (req, res) { ... } } And then map that whole resource under a certain path, "/resources". Further, it is built on sound principles such as, you can't destroy or change anything using GET, you can issue requests other than POST any number of times and nothing will go wrong. Other things like using HTTP headers to decide in which format the consumer wishes to consume the resource, HTTP status codes for error handling, and HATEOAS, gives me the feeling of working with the system instead of building cruft. I argue that REST in fact makes it easier "to maintain and implement the web services". YMMV.
functionform 15y ago
I would say the real power is the simplicity of stateless programming. It's easier to debug and easier to code, thus stronger and faster development. I think a lot of devs assume it just about "using HTTP to its true potential" which is incidental. Other protocols could be implemented in a restful manner.
PaulHoule 15y ago
REST is a scam. For most people, REST is simply the negation of SOAP. They should really use some term like POX (Plain Old XML) or POJ (Plain Old JSON) for simple RPC protocols implemented over http. If I still was interested in being a maintenance programmer, I could make a pretty good living fixing broken systems based on people who drank Fielding's Kool Aid. For instance, I once saw a Silverlight app that took 20 minutes to initialize because it traversed a tree of relationships using REST. It started out O.K. but as the app grew more complicated it took tens of thousands of requests and an incredible amount of latency. I reorganized it so that it got all this information in one POX call that took 2 seconds. A bad architecture slowed the application down by a factor of 600 and made the difference between something that would have worked and something that failed. People who are building toy applications can blubber about "the decoupling of the client from the server" but the #1 delusion in distributed systems is that you can compose distributed operations the same way you compose function calls in a normal program. The issue is that the latency involved in a distributed call is about 100 million times more than that involve in a function call, and the failure rate is more than 10 trillion times more. All of the great distributed algorithms such as Jacobsen's heuristic for TCP and Bittorrent have holistic properties possesed by the system as a whole that are responsible for their success. Hypothetically you could deal with the reliability problems of REST applications by using distributed transactions, but so far as performance and latency goes, this is like putting out a fire with gasoline. Security is another problem with REST. Security rules are usually about state transitions, not about states. To ensure that security (and integrity) constraints are met, REST applications need to contain error prone code that compares the before and after states to check if the transition is legal. This is in contrast to POX/RPC applications in which it is straightforward to analyse the security impacts of individual RPC calls.
- yesbabyyes 15y ago
  Regarding your experiences with the Silverlight app, I don't see that as a case against REST at all. IMO, it's perfectly reasonable to have a view which returns some kind of aggregate resource, while still having endpoints for each individual resource. Or including "sub-resources" as full objects instead of arrays of URIs, or letting the consumer specify their preferred depth of recursion.
mseebach 15y ago
REST is an anti-anti-pattern where the anti-pattern is WS-* and SOAP. If there had never been SOAP, I strongly doubt there would have been a strongly opinionated REST movement. "Little-r REST" is very little on it's own. It's mostly just common sense as settled by about a decade of trial-and-error. I remember dabbling in PHP-RPC about 10 years ago, and most of the takeaways aren't lightyears from what REST is today.
padobson 15y ago
I am beginning to gather from this SO post as well as the other HN link to ShareFile, that REST is not something that can be summed up in a paragraph on HN or SO. This is why the arguments over it are getting heated without seeming to go anywhere. All of the descriptions of REST are met with "That's X, that's not REST. X May be part of REST, but it's not all that REST is". Turning the SO article into a community wiki is probably the way to go, and allow the discussion to expand until someone who reads it is able to get the concept of REST even though they'll never be able to explain it in a paragraph.
brosephius 15y ago
In the accepted answer, what's so bad about the "non-restful" approach the author describes? Who cares if I use GET/DELETE/PUT/POST vs putting the "verb" in a query string argument or the name the file that's being called?
- randomdata 15y ago
  RESTful, as opposed to REST, seems to be clear about the use of HTTP and all of its verbs. It is not RESTful if you do it any other way just by definition. REST itself does not concern itself with the protocol you use. Theoretically you could build a REST protocol over HTTP that does not use HTTP verbs, using it as only a transport layer. Though I'm not sure what you would gain by implementing a REST protocol over another REST protocol. Pragmatically, if you choose to use HTTP, you need to think about the infrastructure that exists. Each verb comes with a very specific meaning, and systems like proxies and other software that come between you and the client will act in different ways depending on which verb you choose. To meet the goals outlined in the REST dissertation, you need to be aware of those behaviours.
AffableSpatula 15y ago
Producing RESTful applications is more of an art than a science. There are two key objectives to bear in mind when designing a web app to be RESTful: - your app should produce client/server interactions which complement the semantics of HTTP. (this makes the interaction visible and helps with intermediate processing e.g. caching) - expose your application in a way that minimizes the assumptions clients can make about it - aka 'HATEOAS' (this will reduce risk when making changes to your application and therefore improve the evolvability of your application)
jalfresi 15y ago
Just thought I'd add that a lot of people are raising the issue of discoverability in restful services. From what I have read this is dealt with with three key constraints: mediatypes, link relations and HATEOAS (hypertext as the engine of application state). Mediatypes provide a standardised way of processing the representations provided to and from a resource (HTML is processed in particular way, as is JSON, as are PNGs, etc). REST has a constraint that requires you use registered mediatypes. On the web, this is the IANA (http://www.iana.org/assignments/media-types/index.html http://www.iana.org/assignments/media-types/index.html). If you mint your own mediatypes and use them on the public web, they must be registered with IANA for a service to be considered RESTful. Link Relations again provide a standardised way of manipulating resources. They describe how resources at the end of a link can be manipulated. Examples include the ATOM edit relation, others include the stylesheet relation. HATEOAS is a constraint that demands that the the client application should move between states by processing the hyperlinks contained within a representation via the relations provided. There are two things you should pick up from this: a general REST client will not be able to do much with a service without knowing how to process the mediatypes of the representations returned by resources, and will not be able to move between states on the client without understanding how to interact with the service via the relations the service uses. Think about the most common REST clients out there: web browsers. If I mint a new mediatype that represents "a visual representation of a kitten with a comical caption", I cannot realistically expect a web browser to understand how to process this. The knowledge of how to process my custom mediatype must be baked into the web browser, much like web browsers know how to process image/* media types. Much the same problem exists with link relations. Most of the time Link Relations are defined with a mediatype (think how a web browser must move to the state of processing a stylesheet by understanding that the link rel "stylesheet" dictates that the user-agent must retrive the stylesheet resource by performing a HTTP GET on the linked resource). RESTful client applications must be able to understand the mediatypes and link relations used in a RESTful web service. These three separate constraints, constraints that must be adhered to to be considered RESTful allow a REST client to navigate a REST service. The beauty here is that the service may change the url space of a service at any point without breaking a client, as the client knows all it needs to know to safely move around the client application state, as the rest is provided by the service on a per request basis. As others have pointed out, caching (another constraint) cuts down on the constant round trips that such a setup would suggest, but I'll leave that constraint for another commenter to flesh out :) Finally, two points: HTTP headers are part of the representation. This means that mediatypes that may at first appear to violate the hypermedia constraint can be made into hypermedia representations via the link header (http://tools.ietf.org/html/draft-nottingham-http-link-header-06 http://tools.ietf.org/html/draft-nottingham-http-link-header...). So PNGs can link to resources that contain metadata with a link relation such as "meta" (for example). Second, many people mention the common HTTP verbs but ignore the OPTIONS verb. Calling OPTIONS on a resource can provide a lot of information back to the client about how they can interact with a resource. I've built systems that provide a list of HTTP verbs that a logged in user may perform on the resource, for example. Different users with different roles may be able to POST or DELETE, whilst others would see that they can only GET. Hopefully this sheds some light on how RESTful services are made discoverable.
dgallagher 15y ago
My $0.02. In general, I've found many people describe something as "RESTful" but not actually know what RESTful truly means. Instead, they use it as an acronym to say "A web-based API", which is not necessarily the same thing as RESTful. The best follow-up question to ask someone is: "What level on the Richardson Maturity Model is your RESTful API?" If they can't answer that, they're probably using the term RESTful to describe something else. Richardson Maturity Model: Level Zero Service - URI API. Usually just POST. SOAP, XML-RPC, POX. Level One Service - URI Tunneling via URI Templates. GET/POST. Level Two Service - CRUD (POST, GET, PUT, DELETE). Amazon S3. Level Three Service - "Hypermedia as the Engine of Application State" (HATEOAS). The higher up the level, the more "RESTful" your API (you can argue about the order of level's 0 and 1), but the more complex it will be. Not everything fits perfectly in those levels either; you're free to borrow concepts and mash-up your own custom API. HATEOAS is the most complicated. Imagine you're browsing the internet. You go to a webpage, and it loads with lots of text, links, images, and videos. You can interact with it, click on links, watch videos, submit a form, and go elsewhere. You have no idea what appeared on the webpage until after you visited it, and the next time you visit it might change entirely. The link might become broken and you get 404'ed, or you need a username/password otherwise you get 401'ed. HATEOAS is similar to that, but instead of a "person" browsing a "website", it's "client software" browsing "XML/URIs/Resources" received from a server API. REST is not easy to understand or explain, as it entails learning about many different concepts, ideas, and custom-building something based on them. This is probably why there's no single-sentence which easily describes REST. Saying that something is RESTful is like saying something is Drivable. You can drive a car, truck, motorcycle, bicycle, or boat, but they're all very different from one another. There are similar concepts between them, like accelerating, steering, breaking, but how they do each of those things is very different. A good book I recommend is "REST in Practice" by Jim Webber, Savas Parastatidis, and Ian Robinson (http://www.amazon.com/REST-Practice-Hypermedia-Systems-Architecture/dp/0596805829 http://www.amazon.com/REST-Practice-Hypermedia-Systems-Archi... or http://shop.oreilly.com/product/9780596805838.do http://shop.oreilly.com/product/9780596805838.do). That helped me grasp what REST means.
- extension 15y ago
  HATEOAS is similar to that, but instead of a "person" browsing a "website", it's "client software" browsing "XML/URIs/Resources" received from a server API. A person browsing a web site is not "like" HATEOAS, it is the canonical example. The client software, in that case, is a web browser.
ilaksh 15y ago
There are two aspects to discoverability: A) listing all of the operations, and B) getting detailed method signatures for a particular operation. A) is a noble idea but so far few people need to automatically discover and consume web services. B is the real issue: something like SOAP was necessary to make RPC possible over the web for typed languages like C# and Java. REST was a counterargument made by some people coming from a dynamic languages standpoint who really didn't need as much information as the statically typed language people. Its too bad that people have taken A so seriously though and gotten confused or misled (probably deliberately) about what SOAP was for and then tried to make REST into that. The most convenient and useful API, even over the web, is one that is as close to normal programming as possible. In other words, RPC-style (or some improvement on that like NowJS). That doesn't mean that you can or should forget that you are making remote calls, it just means that you have less other unrelated plumbing to think about. If you want to do RPC in a dynamic language over the web, NowJS is your model. The problem is that dynamic languages and statically typed languages have different requirements. I don't think that either SOAP or REST are a good solution to making the two styles work together on a web RPC. I think we need to work on that more. I guess one more thing complicating this is the fact that most APIs (just like most software systems in general) are in fact dealing with the standard create, read, update, delete operations on data, with some variations. Batch updates are the most common variation, which you could actually easily extend the CRUD model for. The thing is, you almost always have important deviations from that where the CRUD model doesn't fit. But regardless of whether you are doing CRUD or something else, you still want your API to be as simple and normal as possible and that means RPC. Maybe as some point we can focus more on languages or frameworks that better integrate the CRUD concept and things like calculated fields and aggregation, and transparently handle tasks like persistence and shared state. Just about all of the programs I write need to persist their data and transmit/share their state. Maybe we want a semantic data oriented networking programming system (or more of them). This would be inspired by dynamic languages like JavaScript but necessarily incorporate some kind of typing more integrally (inferred?). Maybe just start with NowJS, bake in some kind of CRUD generation based on nested schema definitions, put that on the server, add a way to indicate that operations need to be batched (for transactional consistency and practical network performance) and make the nice MongoDB criteria and now aggregation stuff baked into the client-side also. That would be cool (much cooler and more useful than me thinking or caring about HTTP PUT or DELETE).

121 points by klochner 15y ago

I write RESTful services, to the best of my ability. Half the tools I use enforce or encourage it. Confession: I don't understand what the advantages are supposed to be. I want to believe it isn't just arbitrary dogma. I really do. Applications don't care about the method or protocol a web service is using. Just get the data to and from. Humans should care about how easy it is to maintain and implement the web services and anything they choose to do to make that goal a reality is good. Oh, it makes for cute looking URIs, I guess.

pfraze 15y ago
For me, it's just a helpful description. I know something about an API if it's RESTful, and I know what others expect from me when I say it. And practically, Backbone.js expects REST conventions from the server API, which is a (small) gain in setup time.
- jebblue 15y ago
  >> I know something about an API if it's RESTful With SOAP, you know everything, just ask the server for its WSDL.
  - scott_w 15y ago
    I'm currently working on a project where the WSDL is broken. The Java application that constructed the WSDL was unaware it was running behind a HTTPS proxy. This led to it importing HTTP URLs that didn't actually work. The solution was to have Suds re-route specific URLs to resolve correctly. The fact that Suds is designed this way is testament to his common this problem is. Yes, you can get HTTP servers that don't respect the safety of Get, but it's a much less common issue.
    - jebblue 15y ago
      I run my Tomcat server with AXIS providing SOAP capabilities on localhost:8080 and front-end it with Apache using ProxyPass and ProxyPassReverse. My SOAP web app runs fine, my Android test client also hits it with no complaints. My Apache server can be hit with both HTTP and HTTPS which lets me use Apache to handle certificate management while I cna run any type of app server on localhost that I want. So far no issues with this scenario. I used this for a contract I was just on and it also worked fine for both the SOAP and REST clients.
RyanMcGreal 15y ago
Here are some benefits: * A RESTful API is discoverable. With no background knowledge, a client can do a GET request on the root URL to get a list of resources with URLS. It's easy to dive right in and quickly figure out what is available. * Developers understand HTTP. REST is essentially just HTTP, and we already understand HTTP. REST means the API developer doesn't need to waste time and energy (badly) reinventing/re-implementing what HTTP does on top of HTTP; and the client doesn't need to waste time and energy learning a bunch of ad hoc protocols. * Our tools understand HTTP. Just about every client language/framework on earth already understands HTTP. Without jumping through any extra hoops, a client working in Python or Ruby or C# or Java or JavaScript or PHP or even VBScript can execute an HTTP request on an API resource and understand the response. * REST keeps us honest. A RESTful API architecture forces the API developer to be clear about what is a resource and what methods clients can execute against each resource. This makes for a better-organized, more orthogonal API.
- ExpiredLink 15y ago
  Experience shows that your benefits are actually myths. A 'RESTful API' is not more discoverable, understandable and 'honest' than any conventional, local or remote API.
- jebblue 15y ago
  >> A RESTful API is discoverable So is SOAP. >> Developers understand HTTP SOAP runs on just about anything including HTTP or even SMTP. >> Our tools understand HTTP SOAP doesn't care what the clients or servers are written in or run on. >> REST keeps us honest I disgree, you can change something in a JSON packet and the client will only know it broke when it's run. With SOAP, if your client uses a compiled language then you as a developer will know first before you give it to a customer to run, you can fix it then.
  - RyanMcGreal 15y ago
    > So is SOAP. No it's not. In theory, you can just consume the WSDL and have all the methods available to you, but in practice, there are huge and unbridgeable issues with interoperability. A C# SOAP client will have trouble consuming a Java WSDL, and so on. > SOAP runs on just about anything including HTTP or even SMTP. SOAP runs on top of HTTP but merely uses HTTP as a tunnel. All the stuff that should be in HTTP - the resource, the method, the data - is inside the XML envelope. If you want to consume a SOAP web service, expect to get your hands dirty. > SOAP doesn't care what the clients or servers are written in or run on. In theory, no. In practice, interoperability is by no means a given. > you can change something in a JSON packet and the client will only know it broke when it's run. That's not really what I was talking about, but if you make a breaking API change in any system, you should have a way to do it so clients aren't caught flat-footed when their app breaks. Neither REST nor SOAP inherently solves this problem, but REST does allow for custom media types that include versioning.
icebraining 15y ago
Each of the constraints brings some advantages to the system. To me, the most important is the decoupling of the client from the server. I think this doesn't seem that important because we still code each client against particular API, but we could adopt true uniform APIs - by not only using the HTTP methods and following HATEOAS, but by also standardizing on data formats that are widely adopted¹ - we would be able to write much more generic clients that could work with different APIs, perhaps even with ones not considered by the developer, without wasting hours upon hours writing code against each service. ¹ No, JSON isn't a standard data format, but more a standard serialization format. You still have to manually code against each service's response types.
funkah 15y ago
I can appreciate making web services a lot simpler than horseshit like SOAP. If all we want to do is get data in and out, let's do it simply and without a bunch of extra ceremony. I can appreciate the notion of using concepts we've already had forever in HTTP rather than reinventing them, poorly. Beyond good common-sense things like this, REST seems to involve a lot of people yelling about whether something is or is not REST.
- jebblue 15y ago
  How about SOAP does computational distribution and REST does data distribution and they are both needed today.
jakejake 15y ago
Theoretically if done correctly then your REST service can be accessed by generic REST clients that don't know about your particular service. Though generic client isn't going to know really what to do with your service. Aside from performing basic CRUD operations, a generic client would have no understanding if what any of it actually means. But, for example you can use code libraries that are designed to work with REST services in your client and not have to write as much boring "plumbing" code.
- extension 15y ago
  Though generic client isn't going to know really what to do with your service. This is where hypermedia comes in. A rich set of standard media types allows your generic client to do useful things without knowing about any particular service.
yesbabyyes 15y ago
In my experience, the biggest win is that it helps me as a developer to create clean interfaces. Whereas a homerolled RPC solution would encourage me to write controllers for different paths, taking arguments in various ways, when writing a REST interface I can create some kind of object: { index: function (req, res) { ... } create: function (req, res) { ... } retrieve: function (req, res) { ... } update: function (req, res) { ... } delete: function (req, res) { ... } } And then map that whole resource under a certain path, "/resources". Further, it is built on sound principles such as, you can't destroy or change anything using GET, you can issue requests other than POST any number of times and nothing will go wrong. Other things like using HTTP headers to decide in which format the consumer wishes to consume the resource, HTTP status codes for error handling, and HATEOAS, gives me the feeling of working with the system instead of building cruft. I argue that REST in fact makes it easier "to maintain and implement the web services". YMMV.

functionform 15y ago

I would say the real power is the simplicity of stateless programming. It's easier to debug and easier to code, thus stronger and faster development. I think a lot of devs assume it just about "using HTTP to its true potential" which is incidental. Other protocols could be implemented in a restful manner.

PaulHoule 15y ago

REST is a scam. For most people, REST is simply the negation of SOAP. They should really use some term like POX (Plain Old XML) or POJ (Plain Old JSON) for simple RPC protocols implemented over http. If I still was interested in being a maintenance programmer, I could make a pretty good living fixing broken systems based on people who drank Fielding's Kool Aid. For instance, I once saw a Silverlight app that took 20 minutes to initialize because it traversed a tree of relationships using REST. It started out O.K. but as the app grew more complicated it took tens of thousands of requests and an incredible amount of latency. I reorganized it so that it got all this information in one POX call that took 2 seconds. A bad architecture slowed the application down by a factor of 600 and made the difference between something that would have worked and something that failed. People who are building toy applications can blubber about "the decoupling of the client from the server" but the #1 delusion in distributed systems is that you can compose distributed operations the same way you compose function calls in a normal program. The issue is that the latency involved in a distributed call is about 100 million times more than that involve in a function call, and the failure rate is more than 10 trillion times more. All of the great distributed algorithms such as Jacobsen's heuristic for TCP and Bittorrent have holistic properties possesed by the system as a whole that are responsible for their success. Hypothetically you could deal with the reliability problems of REST applications by using distributed transactions, but so far as performance and latency goes, this is like putting out a fire with gasoline. Security is another problem with REST. Security rules are usually about state transitions, not about states. To ensure that security (and integrity) constraints are met, REST applications need to contain error prone code that compares the before and after states to check if the transition is legal. This is in contrast to POX/RPC applications in which it is straightforward to analyse the security impacts of individual RPC calls.

yesbabyyes 15y ago
Regarding your experiences with the Silverlight app, I don't see that as a case against REST at all. IMO, it's perfectly reasonable to have a view which returns some kind of aggregate resource, while still having endpoints for each individual resource. Or including "sub-resources" as full objects instead of arrays of URIs, or letting the consumer specify their preferred depth of recursion.

mseebach 15y ago

REST is an anti-anti-pattern where the anti-pattern is WS-* and SOAP. If there had never been SOAP, I strongly doubt there would have been a strongly opinionated REST movement. "Little-r REST" is very little on it's own. It's mostly just common sense as settled by about a decade of trial-and-error. I remember dabbling in PHP-RPC about 10 years ago, and most of the takeaways aren't lightyears from what REST is today.

padobson 15y ago

I am beginning to gather from this SO post as well as the other HN link to ShareFile, that REST is not something that can be summed up in a paragraph on HN or SO. This is why the arguments over it are getting heated without seeming to go anywhere. All of the descriptions of REST are met with "That's X, that's not REST. X May be part of REST, but it's not all that REST is". Turning the SO article into a community wiki is probably the way to go, and allow the discussion to expand until someone who reads it is able to get the concept of REST even though they'll never be able to explain it in a paragraph.

brosephius 15y ago

In the accepted answer, what's so bad about the "non-restful" approach the author describes? Who cares if I use GET/DELETE/PUT/POST vs putting the "verb" in a query string argument or the name the file that's being called?

randomdata 15y ago
RESTful, as opposed to REST, seems to be clear about the use of HTTP and all of its verbs. It is not RESTful if you do it any other way just by definition. REST itself does not concern itself with the protocol you use. Theoretically you could build a REST protocol over HTTP that does not use HTTP verbs, using it as only a transport layer. Though I'm not sure what you would gain by implementing a REST protocol over another REST protocol. Pragmatically, if you choose to use HTTP, you need to think about the infrastructure that exists. Each verb comes with a very specific meaning, and systems like proxies and other software that come between you and the client will act in different ways depending on which verb you choose. To meet the goals outlined in the REST dissertation, you need to be aware of those behaviours.

AffableSpatula 15y ago

Producing RESTful applications is more of an art than a science. There are two key objectives to bear in mind when designing a web app to be RESTful: - your app should produce client/server interactions which complement the semantics of HTTP. (this makes the interaction visible and helps with intermediate processing e.g. caching) - expose your application in a way that minimizes the assumptions clients can make about it - aka 'HATEOAS' (this will reduce risk when making changes to your application and therefore improve the evolvability of your application)

jalfresi 15y ago

Just thought I'd add that a lot of people are raising the issue of discoverability in restful services. From what I have read this is dealt with with three key constraints: mediatypes, link relations and HATEOAS (hypertext as the engine of application state). Mediatypes provide a standardised way of processing the representations provided to and from a resource (HTML is processed in particular way, as is JSON, as are PNGs, etc). REST has a constraint that requires you use registered mediatypes. On the web, this is the IANA (http://www.iana.org/assignments/media-types/index.html http://www.iana.org/assignments/media-types/index.html). If you mint your own mediatypes and use them on the public web, they must be registered with IANA for a service to be considered RESTful. Link Relations again provide a standardised way of manipulating resources. They describe how resources at the end of a link can be manipulated. Examples include the ATOM edit relation, others include the stylesheet relation. HATEOAS is a constraint that demands that the the client application should move between states by processing the hyperlinks contained within a representation via the relations provided. There are two things you should pick up from this: a general REST client will not be able to do much with a service without knowing how to process the mediatypes of the representations returned by resources, and will not be able to move between states on the client without understanding how to interact with the service via the relations the service uses. Think about the most common REST clients out there: web browsers. If I mint a new mediatype that represents "a visual representation of a kitten with a comical caption", I cannot realistically expect a web browser to understand how to process this. The knowledge of how to process my custom mediatype must be baked into the web browser, much like web browsers know how to process image/* media types. Much the same problem exists with link relations. Most of the time Link Relations are defined with a mediatype (think how a web browser must move to the state of processing a stylesheet by understanding that the link rel "stylesheet" dictates that the user-agent must retrive the stylesheet resource by performing a HTTP GET on the linked resource). RESTful client applications must be able to understand the mediatypes and link relations used in a RESTful web service. These three separate constraints, constraints that must be adhered to to be considered RESTful allow a REST client to navigate a REST service. The beauty here is that the service may change the url space of a service at any point without breaking a client, as the client knows all it needs to know to safely move around the client application state, as the rest is provided by the service on a per request basis. As others have pointed out, caching (another constraint) cuts down on the constant round trips that such a setup would suggest, but I'll leave that constraint for another commenter to flesh out :) Finally, two points: HTTP headers are part of the representation. This means that mediatypes that may at first appear to violate the hypermedia constraint can be made into hypermedia representations via the link header (http://tools.ietf.org/html/draft-nottingham-http-link-header-06 http://tools.ietf.org/html/draft-nottingham-http-link-header...). So PNGs can link to resources that contain metadata with a link relation such as "meta" (for example). Second, many people mention the common HTTP verbs but ignore the OPTIONS verb. Calling OPTIONS on a resource can provide a lot of information back to the client about how they can interact with a resource. I've built systems that provide a list of HTTP verbs that a logged in user may perform on the resource, for example. Different users with different roles may be able to POST or DELETE, whilst others would see that they can only GET. Hopefully this sheds some light on how RESTful services are made discoverable.

dgallagher 15y ago

My $0.02. In general, I've found many people describe something as "RESTful" but not actually know what RESTful truly means. Instead, they use it as an acronym to say "A web-based API", which is not necessarily the same thing as RESTful. The best follow-up question to ask someone is: "What level on the Richardson Maturity Model is your RESTful API?" If they can't answer that, they're probably using the term RESTful to describe something else. Richardson Maturity Model: Level Zero Service - URI API. Usually just POST. SOAP, XML-RPC, POX. Level One Service - URI Tunneling via URI Templates. GET/POST. Level Two Service - CRUD (POST, GET, PUT, DELETE). Amazon S3. Level Three Service - "Hypermedia as the Engine of Application State" (HATEOAS). The higher up the level, the more "RESTful" your API (you can argue about the order of level's 0 and 1), but the more complex it will be. Not everything fits perfectly in those levels either; you're free to borrow concepts and mash-up your own custom API. HATEOAS is the most complicated. Imagine you're browsing the internet. You go to a webpage, and it loads with lots of text, links, images, and videos. You can interact with it, click on links, watch videos, submit a form, and go elsewhere. You have no idea what appeared on the webpage until after you visited it, and the next time you visit it might change entirely. The link might become broken and you get 404'ed, or you need a username/password otherwise you get 401'ed. HATEOAS is similar to that, but instead of a "person" browsing a "website", it's "client software" browsing "XML/URIs/Resources" received from a server API. REST is not easy to understand or explain, as it entails learning about many different concepts, ideas, and custom-building something based on them. This is probably why there's no single-sentence which easily describes REST. Saying that something is RESTful is like saying something is Drivable. You can drive a car, truck, motorcycle, bicycle, or boat, but they're all very different from one another. There are similar concepts between them, like accelerating, steering, breaking, but how they do each of those things is very different. A good book I recommend is "REST in Practice" by Jim Webber, Savas Parastatidis, and Ian Robinson (http://www.amazon.com/REST-Practice-Hypermedia-Systems-Architecture/dp/0596805829 http://www.amazon.com/REST-Practice-Hypermedia-Systems-Archi... or http://shop.oreilly.com/product/9780596805838.do http://shop.oreilly.com/product/9780596805838.do). That helped me grasp what REST means.

extension 15y ago
HATEOAS is similar to that, but instead of a "person" browsing a "website", it's "client software" browsing "XML/URIs/Resources" received from a server API. A person browsing a web site is not "like" HATEOAS, it is the canonical example. The client software, in that case, is a web browser.

ilaksh 15y ago

There are two aspects to discoverability: A) listing all of the operations, and B) getting detailed method signatures for a particular operation. A) is a noble idea but so far few people need to automatically discover and consume web services. B is the real issue: something like SOAP was necessary to make RPC possible over the web for typed languages like C# and Java. REST was a counterargument made by some people coming from a dynamic languages standpoint who really didn't need as much information as the statically typed language people. Its too bad that people have taken A so seriously though and gotten confused or misled (probably deliberately) about what SOAP was for and then tried to make REST into that. The most convenient and useful API, even over the web, is one that is as close to normal programming as possible. In other words, RPC-style (or some improvement on that like NowJS). That doesn't mean that you can or should forget that you are making remote calls, it just means that you have less other unrelated plumbing to think about. If you want to do RPC in a dynamic language over the web, NowJS is your model. The problem is that dynamic languages and statically typed languages have different requirements. I don't think that either SOAP or REST are a good solution to making the two styles work together on a web RPC. I think we need to work on that more. I guess one more thing complicating this is the fact that most APIs (just like most software systems in general) are in fact dealing with the standard create, read, update, delete operations on data, with some variations. Batch updates are the most common variation, which you could actually easily extend the CRUD model for. The thing is, you almost always have important deviations from that where the CRUD model doesn't fit. But regardless of whether you are doing CRUD or something else, you still want your API to be as simple and normal as possible and that means RPC. Maybe as some point we can focus more on languages or frameworks that better integrate the CRUD concept and things like calculated fields and aggregation, and transparently handle tasks like persistence and shared state. Just about all of the programs I write need to persist their data and transmit/share their state. Maybe we want a semantic data oriented networking programming system (or more of them). This would be inspired by dynamic languages like JavaScript but necessarily incorporate some kind of typing more integrally (inferred?). Maybe just start with NowJS, bake in some kind of CRUD generation based on nested schema definitions, put that on the server, add a way to indicate that operations need to be batched (for transactional consistency and practical network performance) and make the nice MongoDB criteria and now aggregation stuff baked into the client-side also. That would be cool (much cooler and more useful than me thinking or caring about HTTP PUT or DELETE).