
What RESTful actually means - luu
https://codewords.recurse.com/issues/five/what-restful-actually-means
======
pixie_
REST is the definition of a buzzword. Vague. Useless. Everyone talks about it,
but no one ever 'understands' it. You make your API REST not because you think
it's good, but because everyone else does it. It's instant karma. Like XML was
10 years ago. Who cares if you have to make a lot of ugly confusing endpoints
- at least you can call your API RESTful.

I like how Dropbox bucked the trend and went with a simple POST based API.
JSON parameters in. JSON response out. No complicated urls, strange headers,
verbs, hateoas, etc..

[https://www.dropbox.com/developers/documentation/http/docume...](https://www.dropbox.com/developers/documentation/http/documentation)

~~~
krainboltgreene
> Everyone talks about it, but no one ever 'understands' it.

There are people who understand it to varying degrees. Some who completely
understand it and some who don't understand it at all.

So no, it's not a buzzword, it's just a concept.

PS. Dropbox's API requires a lot of hardcoding because of that very switch.
Hardcoding that HATEOAS lets you avoid.

~~~
tie_
With REST we cannot truly define a degree of understanding. Such a definition
would assume that multiple people know and agree on what would be the full
extent of that understanding. The problem with REST is not the different
_amount_ of knowledge that people possess, but the different _ideas_ that they
have about REST. Which is another way to say that REST is not really a well
defined protocol. (Have you seen similar vague posts titled "What IMAP4
actually means"?)

Because it is not a well defined protocol, you cannot use the same client
library to access random REST APIs. You use/write one library to access
Twitter's REST and another to access Facebook's REST. You could argue that you
use HTTP in both cases, but that's just the underlying transport protocol -
not the API "language" itself. Because of that fact I blame REST for the
millions of developers hours wasted in re-implementations of hundreds and
thousands versions of the same "concept".

The REST "idea" sure looks sexy when you put it next to an atrocity like SOAP,
but that's one of its very few merits.

~~~
JimDabell
> Because it is not a well defined protocol, you cannot use the same client
> library to access random REST APIs.

You misunderstand what REST is. It's not a protocol, it's an architectural
style. Of course you can't build one client library to access arbitrary REST
APIs – that's like complaining that you can't build an object-oriented library
that can be used by any object-oriented language.

REST does, in fact, have a precise definition that is possible to understand
and agree on. It's here:

[https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)

------
teddyh
Related:

Twilio Conference 2011: Steve Klabnik, Everything You Know About REST Is
Wrong: [http://vimeo.com/30764565](http://vimeo.com/30764565)

REST APIs must be hypertext-driven: [http://roy.gbiv.com/untangled/2008/rest-
apis-must-be-hyperte...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hypertext-driven)

Hypermedia APIs - Jon Moore:
[http://vimeo.com/20781278](http://vimeo.com/20781278)

Designing a RESTful Web API:
[http://blog.luisrei.com/articles/rest.html](http://blog.luisrei.com/articles/rest.html)

------
aikah
RESTful doesn't mean anything no more than REST means anything, precisely
because it's NOT A PROTOCOL and THERE IS NO NORMATIVE SPEC. All this fiasco is
due to a vague set of ideas that are in practice no more than JSON-RPC with a
http header.

I'm sure you can find 50 developers that will disagree on your definition and
that's what hurts all the REST advocates. Your definition is as valid as
theirs, until there is a spec that explains precisely what REST is. There is
none, there is no normative spec, period.

SOAP has a spec, RPC has a spec, GraphQL has a spec. "REST"(full) has no spec,
REST is whatever you think it is.

~~~
mwcampbell
> REST is whatever you think it is.

Nonsense. REST is what Dr. Fielding says it is, because he coined the term.

~~~
t-schill
And REST as Dr. Fielding says it is is not as practical to implement as it
should be. Hence the need for RESTful which just draws influence from his
work.

~~~
mwcampbell
What makes REST impractical?

And if REST isn't practical, we should use a different term to describe what
we implement instead.

The meanings of words should be immutable, to avoid confusion. No, that's not
how language has historically worked, but we can do better. After all, there
are a lot of things we have historically done that we don't want to keep
doing.

~~~
dvanduzer
Why would speaking a human language without nuance, without any possibility of
misinterpretation, be a step forward?

It's spelled ReST.

Does that better convey what it _means_ in that string of characters? Maybe
for some values of human. But words are for humans, and humans are not
immutable, so our words shouldn't be.

~~~
antod
_> It's spelled ReST._

Really? It's been capitalized REST everywhere I've seen it.

Including here:
[http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch...](http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)

You weren't thinking of 'reST' (reStructuredText) were you?

~~~
dvanduzer
No, I was thinking of Representational State Transfer, which is what
Fielding's paper talks about. And I was also thinking about how people say
RESTful, and how that's a confusing way to say "conforms to how Roy Fielding
thinks an API should behave."

What I was responding to was advocacy that _human_ language should behave the
way we expect RFCs to work.

------
politician
REST isn't a protocol, it's an argument for an approach to systems
architecture that minimizes coupling between components while maximizing
client reuse.

I've designed and operated several REST-inspired systems over the years, and
let me warn you: it's no walk in the park. Engineers that want to "get it done
now" must be convinced not to huck everything up to the server as a POST.
Founders have to see the business case for every new system. Other departments
may have to relearn tools for interoperating with the systems. It's a whole
big deal. You can't deploy a RESTful solution and avoid dealing with _people_.

For your effort, you'll receive a system with well-factored bounded contexts
whose self-descriptive interfaces interoperate with standardized tooling and
monitoring systems. Projects can be factored into tasks along clear domains
and often incrementally delivered into production. Life-sucking productivity
projects like the _secret admin website_ can be pushed off indefinitely.
Problems will be simple to isolate and reproduce. You'll have the flexibility
to rush out brand new client experiences on tight deadlines.

Notice how none of the problems or benefits really involve a particular
technology tool or framework or language?

In my opinion, ignorance of the significant cultural factors required for a
successful deployment of a RESTful system is _the_ reason why articles
continue to be published about how it's vague or difficult or whatever.

~~~
jmcqk6
There are lots and lots of open source web applications out there. I like to
read code to see how things are being done. Can you point to any web
application out there, with source code available to read, that is built in
the way that you are describing?

------
jalfresi
For me personally, the two most important constraints for a legitimate ReST
application are:

\- HATEOAS \- registered mime-types

In particular, the use of registered mime-types. An example:

Say we are building a restful music service similar to Spotify. Say we focus
on the list of as users playlists. We can embody the currently logged in users
list of playlists as a resource with a specific URL. This URL is opaque to
both the client and server.

The representation of this list of playlists could be in the form of a Json
hash where key is the playlist name and the value is the URL for the playlist
itself.

We also could declare that the following interactions are available to any
client that receives this payload from a HTTP GET request: \- Create a new
playlist \- delete a playlist And therefore we can fulfil the HATEOAS
requirement.

As I understand it, in order to make this restful we must register this as a
custome media type as the additional actions we have defined are part of the
available interactions with this media-type.

Don't confuse the content of the representation with a definition of a media-
type; we could declare our custom media-type as so:

Application/vnd.spotify.com.list.playlists+Json

It is the definition of the media type that dictates that the HATEOAS links in
the header with the rel type of create or delete of how clients should
interpret them. It is this media-type that dictates this.

It is my understanding that pumping raw Json over http, even with HATEOAS in
the headers (or even worse, with links embedded in the Json with the out of
band knowledge that a client should interpret our key/value pairs as hypertext
based only on the resource URL) is not in anyway restful.

------
xirdstl
Attempting to define REST is the best way to troll web developers.

------
markbnj
RESTful is not a spec, as has been pointed out: it's an idea. It's much more
like other large-scale design patterns than it is a protocol. Think "object
oriented," or "procedural," not "http" or "tcp." There is only one correct way
to implement/use a protocol, but there are many valid expressions of a pattern
or idea. It's more or less accepted, I think, that the vast majority of
"RESTful" implementation don't obey all the original (15 year old!)
guidelines.

~~~
emmelaich
It is far more (fundamental) and less (design patterny) than that.

It is akin to to functional programming or declarative database queries.
Neither of these are large-scale patterns.

They're both very much about a sane, easy to understand api.

------
adamzerner
> Stateless does not mean that servers and clients do not have state, it
> simply means that they do not need to keep track of each other’s state.

For this reason, I've always thought that the term "stateless" is confusing.
Maybe "client state independent" (the response that the server sends back is
independent of the client's state)? I don't love that term, any better ideas?

~~~
markbnj
I don't think it's confusing because it says exactly what it is supposed to
say. 'Stateless' is not a property of the client, or the server, but of the
relationship between them, and that relationship is expressed in the protocol
they use to communicate.

~~~
tie_
The relationship between client and server is not stateless in the majority of
the cases. Most of the implementations rely on authentication state (cookie,
session secret). Very few actually do the stateless part right.

~~~
kuschku
If your authentication token times out, it’s not ReST.

As simple as that.

~~~
e12e
If you're using an authentication token, it's not really REST. Because of the
dire situation wrt. client certificates, the only straight-forward, "pure"
REST, would be to supply Basic Auth on every request (that doesn't allow
anonymous access).

I'm not really convinced that's _not_ a good idea for a TLS-only service
(compared to the complexities that tokens/cookies introduce). One reason why
there was a move away from Basic Auth was ofcourse that it is crazy to send
plain-text login/password pairs over a plain-text transport (HTTP sans S).

And there's never been any working, cross-platform effort to improve things
(AFAIK).

There's some work on Kerberos that's interesting, but again, many of these
efforts have been simply co-opted by the fact that everyone used cookies (and
had problems, and started encrypting them etc), and _then_ moved from HTTP to
HTTPS.

When you have HTTPS, there's not that many reasons to not just have "SECRET
PASSWORD" in the URL (granted that'd not be REST either, but BASIC AUTH does
the same thing, just in a header).

~~~
kuschku
Indeed, this is the point I wanted to get to.

If you have to do a challenge-response auth every 5 requests, or so, to get a
session, then it’s not really rest.

Client certificates might actually make the most sense in this case.

------
sopooneo
I'm reading here that a big problem with many REST APIs is that they don't go
all the way with the concept. They fall short of the total, so miss out on the
overall benefit.

But if there are any here who are strong advocates, I truly want to know, how
do we authenticate in a REST compliment way in practice? Must we, as was
pushed early on, only use HTTP basic auth, and resend credentials with each
request? Or do we treat the session itself as resource, and somehow refernce
it in requests for all other resources? Or are session cookies somehow exempt
from the rule that _interactions_ must be stateless?

~~~
machuidel
Actually, they are all valid ways when using the ReST philosophy. The idea is
that with every request from the client the latest state is sent along with it
(if needed). This way the state of the request can be reconstructed on the
server without depending on centralized storage or a single server. The server
may update the state and return it for the client to store again (some parts
encrypted if needed). No need for the server to keep the state (this way it
can remain stateless).

HTTP basic auth does this automatically.

Creating a resource for a session is optional but may be useful if the state
to sent back and forth is too big. But this will require centralized storage.

The state may be stored inside a cookie where parts of it can be encrypted. It
is also possible to specify that parts can only be updated by the server.

You may also use Local Storage and send the data across using an
XMLHttpRequest or even use a HTML form (which may have limited support for the
HTTP verbs).

Read my other comment for more information.

~~~
sopooneo
But it seems to me that ReST _does_ dictate, specifically, that there must be
no need for shared state. The system _must_ work without the client having
knowledge of the server and vice versa. But a cookie, as used to hold a
session token which references information on the server, is very much shared
state. So should be forbidden.

~~~
machuidel
The state is passed back and forth. The server does not keep the state (that
is why they call it stateless), the client may keep it. If something does need
to be stored on the server a resource should be created. The state that is
passed back and forth may then contain a reference to the resource, a resource
identifier (in case of the web usually a URI is being used).

The server is stateless because it receives the latest state from the client
(location, cookie and other headers) and sends an new updated state (location,
set-cookie and other headers) to the client again along with an optional
representation. There is no need for the server to keep the state in memory
anymore. Because the server does not keep the state it does not matter which
copy of the server (in case of load-balancing or fail-over etc.) handles the
next request as everything needed can be derived from the state sent along
with request from the client.

Keep in mind that it is best practice to be able to reproduce a representation
by the use of a resource identifier, like with "pure functions" in functional
programming, it should be deterministic. The content of a representation may
change but not the semantics of it.

The part that is stateful is the state that is being passed back and forth
between the client and the server.

Does that answer your question?

------
virde
Here's a link to a rant I wrote earlier this year on the same topic

[https://medium.com/@vrashabhirde/will-the-real-restful-
api-p...](https://medium.com/@vrashabhirde/will-the-real-restful-api-please-
stand-up-ea612a92b9a9#.88ft4t66s)

(edited again to make it less rant-y and offensive and more useful)

------
vbezhenar
Can someone suggest an example of "true" REST API, complex enough (not trivial
CRUD stuff like blog) to be used as a real-life example?

~~~
nbrempel
I look to Stripe's API as the ultimate REST example -
[https://stripe.com/docs/api](https://stripe.com/docs/api).

It's very complicated and follows the pattern very closely.

~~~
mahmoudimus
Stripe's API is good, but it is far from the "ultimate REST example." What is
the statistical sample set of APIs that you are comparing from?

From my experience, I would suggest something like Twilio, Github or FoxyCart
as the epitome of a REST API.

------
7ewis
ELI5 for a non-developer?

I always thought it was just a way of sending commands or data to a sever. I
created a RESTful (I think) service on a Raspberry Pi that powered on a light
every time it got an alert from Salesforce. It did this by POSTing to power.py
and parsing in some variables. Is that RESTful?

~~~
herge
REST is a series of principals used to structure APIs. Think about if you had
a lot more lights on your Raspberry PI. A simple way would be having a call
lighting up a specific light. But then the client must track state, in terme
of rembering which lights are lit. In a REST sister, you'd request the state
of all the lights (typically through a GET http request), which the server
would track for you. Then you'd send back the lit or unlit state of all the
lights, thereby setting a new state (typically, again, through an http POST
request).

~~~
sokoloff
I don't see anything non-RESTy about your former example (and would argue it's
a BETTER protocol design).

Imagine we want to change the state of light 7 (and only light 7).

A PUT/PATCH of "ON" "OFF" (or 1 or 0 or a float for a dimmer) to
[http://raspberry1.local/lights/7](http://raspberry1.local/lights/7) to change
the status of light 7 is better IMO than doing a GET to
[http://raspberry1.local/lights](http://raspberry1.local/lights) and then a
PUTS/PATCH to that same URL to update all lights status for the purpose of
just updating one light. The latter is obviously fragile in the face of
multiple writers (you'll lose updates on overlapping but not colliding writes-
an update to light 6 that overlaps in time with light 7 can result in the
earlier of those updates being lost when there's no inherent reason for it).

~~~
Mandatum
It really depends on the amount of calls you'll have to make. What if you had
10,000 lights? What we tend to do is allow for partial updates with PATCH on
just the lights you'd want to change.

ie

PATCH [http://bla/url/lights](http://bla/url/lights)

{ light1: ON, light351: ON, light 4672: ON }

I think that since generally documentation around RESTful API's is generally
very good with in-browser demo calls, interpretation of the REST API although
differs between implementors, is generally relatively similar enough.

However there are cases where REST design just won't work, or implementing the
design abstracts work from the API supplier to the consumer. Where once a
"runThisScript(object)" would be easy enough for a developer, now the script
itself must be implemented by the developer to call the RESTful endpoints.

In cases like this, we occasionally break REST design for the convenience of
developers.

~~~
steveklabnik
Nothing about this alternative version is any more or less RESTful than the
original version.

~~~
Mandatum
Generally HTTP REST works on the idea of resources and properties.

so: /lights /lights/light-id /lights/light-id/wattage (return wattage of
light)

Doing something like:

/lights/light-id/book-janitor-to-replace which might email and update the
janitor's calendar/ToDo list, isn't really following the existing API design.

~~~
gkop
What do you mean "following the existing API design"?

A good API imo would hide the janitor's calendar/ToDo list unless it was
absolutely necessary for the client to access it directly. Then an argument
could be made in favor of the booking janitor endpoint on a light - and the
API is no less RESTful.

Edit: I don't like it when people over-emphasize resources when talking about
REST. I blame this practice on Rails being many people's first introduction to
REST. But Rails isn't actually RESTful per Fielding. I prefer to use the term
resourceful API to describe the kind of API Rails prescribes. REST is
generally in favor of custom endpoints that hide complexity from the client,
even at the expense of having a clear cut decision on eg. POST vs PUT/PATCH
for a given endpoint.

------
machuidel
Have been using the ReST philosophy (or pattern?) for almost 15 years without
any issues. ReST itself does not define the use of a specific technology and
is not a standard by itself, it is pretty abstract. Using the URI and HTTP
standards are just a way to apply it. Other technologies can be used as well,
like SMTP / MIME or something developed yourself as soon as the ReST
constraints can be applied. Adding the ReST constraints is what brings the
advantages. It is really flexible and allows for easy composition of "layers"
through "connectors". A caching proxy is an example of a "connector". If ReST
could be compared to something in programming it is very similar to "monads"
as used in functional programming.

Recursion can be done by the use of nested "resource identifiers" (SSI or ESI
for example) inside the returned "representation". A "connector" may then
decide to do another request to replace the "identifier". If the "connector"
uses caching it may not even need to do another sub-request. I use this to do
something like what Facebook's Relay does. As the full state is always being
sent along with every request it is very easy to scale because the servers,
wherever they are, always have enough context to be able to work with it. A
server may even ignore what it does not understand for the next layer to
handle it called "partial understanding" which is supported by XML for
example. Unfortunately when using JSON most of these advantages are lost. That
is why I prefer a less verbose "XML Infoset" similar to JSON while still
keeping all the advantages.

------
pbreit
This is sorta helpful. But what would be illuminating and almost never gets
done is the very simple description of what a real world API would look like
that corresponds to the description. And there are zillions to choose from to
take a crack at.

------
wstrange
If you have an interest in distributed computing "The End of Protocols" is a
great read:

[http://www.cc.gatech.edu/~keith/classes/ubicomplexity/pdfs/i...](http://www.cc.gatech.edu/~keith/classes/ubicomplexity/pdfs/infra/waldo-
end-of-proto.pdf)

The whole RPC vs. REST thing is not a useful distinction.

------
deeteecee
my only question regarding RESTful api's is... is it really that hard to
implement?

I know there's a few set of rules/principles to follow but in the end, I just
see "lets make a readable and easy-to-understand API that has a nice set of
plural "subjects" with the basic HTTP request verbs all nicely applied.

I ask this because I noticed while applying for jobs, that some people hiring
simply want someone who can write a REST API but I just didn't see it as a big
deal when you're hiring a web developer as long as he has the experience and
good mentality for creating organized code.

------
cuillevel3
Also there is this 5 year old book "REST in Practice" which defines several
levels of RESTfulness

------
hashkb
I ask candidates to explain this when I interview them. I read that first
paragraph and was upset/unsurprised.

~~~
andreyf
What do you expect them to respond? It's not very well defined.

I would probably say...

""" REST, like many great religious philosophies, combines with one's life
experience to mean something different for every pair of eyes that looks at
it. For me, it's something which has URLs for resources of the form

    
    
        /<class_name>(/<instance_id>(/<custom_method>)?)?
    

and default HTTP methods of GET / POST / DELETE to read / modify / remove
instances. Finally, while I realize this is a bit too implementation detail-y
than most definitions, my mind is not really at rest unless an HTTP API
respond with JSON and reference other instances in some standardized way.

You will notice the repetition of sets of 3, and that's because 3 is my
favorite number. I also really like the Stripe API's way of specifying arrows
to related content to "unfold" references in the JSON response. That really
puts my mind at rest when I see it, so that's RESTful, as well.

To get a little more real, though, REST is totally the old hotness and verging
on not even being that hot. All the cool kids now know to use GraphQL, and if
you aren't at least planning to transition to it, I'm not really interested in
working here unless you pay me a lot of money. """

How'd I do?

~~~
arethuza
Well, strictly speaking if your having to explain the structure of your URLs
then it's not really fully REST (because of HATEOS) and I don't think there is
any requirement for a RESTful interface to return JSON.

But having said that I've got the point where I don't really care - if I can
interact with an API from curl without too much difficulty I don't care if the
API is fully REST or not.

~~~
andreyf
I'm deeply offended that you called my URL structure un-REST-ful and challenge
you to come up with an API spec that's more REST-ful than mine.

------
jholman
So what do you call a system that uses more than two HTTP methods (e.g. uses
PUT and DELETE as well as GET and POST), and has marginally-more-human-
readable URLs, but doesn't send self-descriptive representations, doesn't use
hypermedia, doesn't Transfer REpresentational State, and probably also isn't
stateless?

I mean, statistically speaking, if you have such a system, my bet is that you
call that system RESTful. Furthermore, if you have such a system, you vastly
outnumber the people building systems that obey Fielding's constraints. So in
practice, you win the argument about what "RESTful" means.

Can we please stop legitimizing Rails's whimsical aesthetic choices by
pretending that they have something to do with an academically-justified
architecture, and just accept that they're just another way of ripping your
denim and then safety-pinning it closed, by which you demonstrate that you're
not a square and you don't write Java.

~~~
dang
> _Can we please stop legitimizing Rails 's whimsical aesthetic choices by
> pretending that they have something to do with an academically-justified
> architecture, and just accept that they're just another way of ripping your
> denim and then safety-pinning it closed, by which you demonstrate that
> you're not a square and you don't write Java._

Please don't do this here. Snark like this is good for starting technical
flamewars but it invariably lowers the quality of the discussion.

~~~
brazzledazzle
Even though you're right this line almost made it all worth it in terms of
comedic value: "...accept that they're just another way of ripping your denim
and then safety-pinning it closed, by which you demonstrate that you're not a
square and you don't write Java."

