
What exactly is RESTful programming? - klochner
http://stackoverflow.com/questions/671118/what-exactly-is-restful-programming
======
PaulHoule
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.

~~~
AffableSpatula
REST is not a scam, it's THE term for the underlying architectural style of
the web.

Your straw-man interpretation is a scam.

The crappy silverlight app is badly designed and the performance issues you
were seeing can be optimised away trivially. (create a new composite resource
which can represent the entire tree in one go). That is nothing to do with
REST.

"the #1 delusion in distributed systems is that you can compose distributed
operations the same way you compose function calls in a normal program" - This
is exactly what REST addresses as a style.. i.e. REST is not RPC.

Latency is another issue which REST addresses directly. This is why caching is
an explicit constraint.

I have no idea what your point is re: security, sorry. Modelling state
transitions is not that difficult, many languages have existing tools to help
you do this.

~~~
tptacek
People say stuff like "[REST is] THE term for the underlying architectural
style of the web", but that assertion is pretty much back-rationalized onto
the web. I know I'm not the only HN'er who was there at the beginning for
HTTP, and this conceptual purity that RESTians allude to just wasn't there.

For as long as there has been a web, there has been at least one (often more
than one) conceptual ideal claimed to be the heart of the World Wide Web. The
reality is that the whole system is hacked together. Things that work well
tend to be discovered, re-discovered, and perpetuated --- but that doesn't
make any of them the web's "underlying architectural style".

I tend to buy the idea that REST-ish-ness makes for better, clearer, more
usable APIs than RPC. But I also think REST needs to win on the merits, not by
waving some imaginary "REST is the web" flag.

~~~
parasubvert
The reality is that both are true - there was an "HTTP Object Model" that TBL
and Roy Fielding had in mind in the 90s, but it was never formalized until
Roy's thesis. Not everyone on the various IETF and W3C committees understood
or agreed with it, clearly, and there are a lot of hacks in practice. There
were attempts like HTTP-NG to supplant HTTP with CORBA-like Object RPC, but
the arguments against this were basically informal arguments in favour of the
uniform interface of URI + HTTP + MIME. Even today, the current HTML5 leads
don't particularly seem to have much appreciation for the style.

That said, starting with the Apache web server, Roy had a lot of control with
its architecture and approach to supporting particular HTTP features, using
his mental model of the "Web's architectural style" to guide it. After 2000
and the thesis, there are many people that started implementing their clients
and servers with the style as a philosophical guide.

The style also tends to be widely misunderstood and buzzword-ified, which is
scammy.

~~~
tptacek
I'm not sure I buy the argument that being a key contributor to Apache gave
Fielding a huge amount of influence over the architectural style of web
applications. The barn door on that was opened with CGI, and since then, the
architecture of web applications mostly been up to the market and the lowest
common denominator of programmers.

~~~
parasubvert
I was not referring to the internal architecture of web applications inside an
origin server. I was referring to the architecture of a web application across
the various components (agent, proxy, gateway, server), connectors (client,
server, cache, resolver, tunnel), and data elements (resource, identifier,
representation, metadata) in the style.

The architecture of those _interactions_ has remained fairly stable over the
past 15 years, even specs that route around REST like WebSockets are trying to
at least adopt the HTTP upgrade & tunnel connector (HTTP CONNECT) to ensure it
integrates consistently with the style.

------
mseebach
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.

------
nsxwolf
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.

~~~
RyanMcGreal
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.

~~~
jebblue
>> 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
> 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.

~~~
count
> 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.

This is something I have a hard time understanding. Your hypothetical generic
REST client will have a hard time understanding my HATEOAS, discoverable,
fully REST-ified service, if it has no idea what the service is supposed to do
contextually. If my 'blog' resource has links to 'metadata' and 'related'
things, without knowing what those are, how does a 'generic' REST client do
anything with them?

How is that significantly different than SOAP?

I would love to see an actual example of the difference, rather than abstract
discussion, as this is the point I have the hardest time understanding.

~~~
parasubvert
The only difference between REST-in-practice-today and WSDL is that you aren't
expected to map each network interaction to a single procedure call. This
makes a number of things easier: cache the results, GET data across many
different endpoints if you know the format, enable data and metadata
extensibility through the payload, and follow hyperlinks if you know the link
relation and target format.

The Facebook Graph API is a great practical example of this ease of use in
practice: <https://developers.facebook.com/docs/reference/api/>

You're quite right that things like "related" and "metadata" link relations
mean nothing if you don't know what those mean - they are hooks for future
bits of agreement. The difference between REST and WSDL in the long run, in my
opinion, is the practical composability of small bits of agreement (or specs).
The Web Services stack (SOAP, WSDL, WS-*) has had a very difficult time
composing a bunch of specs together as the kernel of their agreement is
basically the XML Infoset. With the RESTful Web, the kernel is HTTP, URI, and
MIME (for now), which has endured a number of extensions (Flash, HTML5,
Atom/RSS, etc.) and evolutions (the rise of mobile devices).

~~~
javascriptlol
Caching at the architecture level has caused more problems than it has solved.
How many times have you heard the phrase "empty your cache, then try again..".
Utterly stupid. This is an optimisation that should be implemented by the
application designer as needed, and if it is within their capabilities.

------
padobson
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.

------
dgallagher
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-Archi...](http://www.amazon.com/REST-Practice-Hypermedia-
Systems-Architecture/dp/0596805829) or
<http://shop.oreilly.com/product/9780596805838.do>). That helped me grasp what
REST means.

~~~
extension
_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.

------
brosephius
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
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.

------
functionform
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.

------
AffableSpatula
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
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>). 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...](http://tools.ietf.org/html/draft-nottingham-http-link-header-06)).
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.

~~~
jsdalton
What syntax should one use to define link relationships in a RESTful service?

Most of the examples I've seen extolling the virtues of HATEOAS use XML,
specifically the <link uri="..." rel="..." /> element. That's great for a
single media type (XML), but what about JSON, which is by far the dominant
media type used in RESTful APIs?

A google search for "hateoas json":
[https://www.google.com/#q=hateoas+json&fp=1](https://www.google.com/#q=hateoas+json&fp=1)

reveals...a bunch of people asking how to format link relations in JSON,
without a definitive answer that I can see.

HATEOAS and discoverability are principles that _sound_ great in high-level
discussions but I have yet to see them implemented in a meaningful, helpful
way.

Anyhow, you seem quite knowledgable on the subject so perhaps you can
enlighten me. Usually it's my own ignorance/obstinateness that's to blame
rather than a flaw in the concepts themselves...

~~~
scott_w
I would argue that you don't. JSON isn't a format for HATEOAS, for the reason
you state. I'm leaning towards saying HTML 5, with some of the new semantic
markup, though it's not perfect.

You can use both, and simply use the Accept HTTP header to determine which
format you want. It gives you both discoverability of HTML (with <a>), and
data transfer that is easy to parse.

------
ilaksh
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).

