
Problems with RESTful APIs (2015) - jaequery
https://mmikowski.github.io/the_lie/
======
derefr
The "true spirit" of REST, to me, is that there's a certain set of things you
can do when creating an API that will let you re-use the huge amount of HTTP
middleware that's been written and get correct (and useful!) semantics from
it. Caches (browser-, edge-, and server-side-), load balancers, forward- and
reverse-proxies, application-layer firewalls, etc. will all "just work" for
your software if you do REST correctly, and won't have any weird edge-cases.

Re-implementing those same semantics in your own messaging protocol / format,
_without_ intertwining the concerns of the protocol and the message format,
throws away any/all of those benefits. You need a protocol that guarantees
that middleware can "look inside" the messages it's passing (or at least their
metadata), in order for any of this to work. _That 's_ why HTTP has both a
transparent part (req path+headers; resp status code) and an opaque part (req
and resp bodies) to each message: the transparent part is there for data that
affects middleware behavior, while the opaque part is there for data that
doesn't.

Note that that doesn't mean you're stuck with HTTP1. SPDY/HTTP2 is effectively
an entirely different _protocol_ —but it keeps the same semantics of requiring
certain properties of the metadata tagged onto each message at the protocol
level, so that anything that speaks the protocol can use that metadata to
inform its decisions.

~~~
quanticle

        The "true spirit" of REST, to me, is that there's a certain set of things 
        you can do when creating an API that will let you re-use the huge amount of 
        HTTP middleware that's been written and get correct (and useful!) semantics 
        from it. Caches (browser-, edge-, and server-side-), load balancers, 
        forward- and reverse-proxies, application-layer firewalls, etc. will all 
        "just work" for your software if you do REST correctly, and won't have any 
        weird edge-cases.
    

Doesn't that assume that the middleware also implements REST correctly? As the
article points out, there are all too many HTTP libraries that only support
GET and POST, not the more "esoteric" verbs like PUT and DELETE.

~~~
SEJeff
Or (for REST apis that might need concurrent updates of the same model) the
most awesome "esoteric" verb, PATCH

~~~
Mikhail_Edoshin
Look into WebDAV and you'll find plenty :) LOCK, UNLOCK, COPY, MOVE, MKCOL,
PROPFIND, PROPPATCH. And also REPORT, SEARCH, and various version-control
operations.

~~~
SEJeff
Oh sure, but the context is REST apis, not WebDAV :)

PATCH allows two users to update different fields on the same resource at the
same time with no conflicts. Otherwise, they'd use PUT and the last update
would win unless they use something (client-side) such as compare and set.

------
Waterluvian
When I was given the task of defining how our multi-robot server would
interface with our user interfaces, I eventually settled on REST. Most of what
I knew about REST had been obtained that week. I implemented something pretty
vanilla with Django and it all felt pretty elegant. I didn't have to worry
about defining a protocol, there was pretty much already one for me:

\- GET, PUT, POST, DELETE (I learned there were others but were kind of
niche/obsolete)

\- 200s for success, 400s for client (request) error, 500s for server error.

It was all nice and worked great (and still does, years later).

But over time numerous people started told me that no it's actually all wrong
for one reason or another. I've heard that I should never use anything except
GET and POST. That I should _ALWAYS_ return a 200 and provide error metadata
as a response if there actually was an error. That POST is actually meant for
updates and PUT is meant for new entities. That the opposite is true. That
neither is true and I should _always_ use POST for any mutation of state. etc.

I feel like I had success because I approached it from a position of
ignorance, meaning I just implemented a simple, sane REST API and was none the
wiser that I was doing it wrong.

~~~
masklinn
> I feel like I had success because I approached it from a position of
> ignorance, meaning I just implemented a simple, sane REST API and was none
> the wiser that I was doing it wrong.

None of it is REST though, it's just one more RPC over HTTP protocol, which is
also what TFAA advertises. Though your version uses HTTP as more than a
trivial transport which I guess is nice.

~~~
Waterluvian
We read then manipulate the state of a multi-robot fleet by making HTTP GET,
PUT, POST, DELETE calls that affect a database and robot broker/manager
services. The state of the robots and the configuration of the system is
represented in JSON. Interaction with the system is stateless, meaning you can
jump in at any time, understand the full state of the system, and manipulate
it safely. Interaction of a healthy system will involve numerous physical and
virtual clients/servers, many of which are physically on the move most of the
time.

If this isn't REST then the Wikipedia page on REST needs updating or I'm just
not explaining it well enough.

~~~
eicnix
I agree that the communication you described isn't completely REST style but
rather "just" using HTTP as an application protocol. There is no real downside
in doing so but it shouldn't be called REST.

REST based on the Richardson maturity model[1] involves:

Level 0: Using HTTP as the transport protocol: e.g. SOAP

Level 1: Identifiable objects: e.g. /object/object_id

Level 2: Using HTTP as the application protocol: e.g. Using POST to create new
objects and DELETE to remove them

Level 3: HATEOAS

[1]
[https://martinfowler.com/articles/richardsonMaturityModel.ht...](https://martinfowler.com/articles/richardsonMaturityModel.html)

~~~
Waterluvian
I'm not sure where I misguided people that I was just doing RPC. Almost all
endpoints are as you described:

`/robots/robot_id/exceptions`

`/maps/map_id/destinations`

`/maps/map_id/areas/speed_limit_areas`

Performing operations is not done via. RPC but rather POSTing a new `mission`
to the queue.

There's no HATEOS but that would generally be silly, since this isn't an API
that requires easy discovery and consumption by third parties. I'm not sure I
subscribe to the HATEOS required for REST, but I don't really care to argue.

I think I'm starting to get a sense that people can be _really_ opinionated on
this stuff, and I'm still lost as to what there is to gain by it. To suggest
what I'm describing isn't REST would be to say that the first sections of the
Wikipedia page are wrong. So are we so far off-base that we need to revise the
Wikipedia page? Or is this more just an opinion?

Thanks for sharing your thoughts. Maybe there's a chance to de-mystify my
confusion on why there's so many opinions on something that, to me, seems so
simple to define.

~~~
masklinn
> I'm not sure where I misguided people that I was just doing RPC.

Sadly the person you respond to is an idiot, their points 1 and 3 have
literally nothing to do with REST. You could have all endpoints be /435645646
yet do rest, you can have the most beautifully crafted URLs in the world and
do rpc, they're orthogonal concerns. Most people do the latter, incidentally.

> Performing operations is not done via. RPC but rather POSTing a new
> `mission` to the queue.

That's still RPC. Encoding your procedure calls via HTTP verbs doesn't make it
not RPC, it makes it (as originally noted) leverage HTTP as more than a
trivial transport.

> There's no HATEOS

So it's not REST, HATEOAS/hyperlinking is the one thing that qualifies your
API as REST according to the bloke who originally defined that term:
[http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hyperte...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven)

> I think I'm starting to get a sense that people can be really opinionated on
> this stuff

Well yeah imagine you see a nice essay defining or formalising a concept
(hyperlinked application interfaces) and creating a word/acronym for it
(REST), then you see the world around it coopt it without any of the meaning
to qualify something which already existed but has seemingly fallen out of
fashion (RPC in this case). That's bothersome.

> seems so simple to define.

If your simple definition of REST is just that you're using HTTP, why would
you need a separate acronym for it?

~~~
deckiedan
> Sadly the person you respond to is an idiot,

"Somewhat misguided" is a lot less harsh and confrontational, FWIW. HN
civility guidelines and all.

------
codr4life
I'm going to have to call bullshit on that one. REST is one of the more
successful strategies we've come up with for connecting systems, this is just
another case of letting perfect stand in the way of good enough. Using GET for
non-destructive operations and POST for updates and deletes is a nice,
portable compromise. I've been trying hard for years to find a reason to
bother with PUT, but so far I've found it not worth the effort.

~~~
rantanplan
> I've been trying hard for years to find a reason to bother with PUT, but so
> far I've found it not worth the effort.

And right there, at your final sentence, you basically described why REST has
more or less failed.

GET and POST are useless for implementing a complete application protocol.
You'd basically overload these http verbs to the point where you would
implement your own protocol. And that's what most people do anyway. You choose
to not use PUT, some other person chooses to not use PATCH or HEAD and I
choose to curse vehemently every time I have to use someone's service.

REST is nothing but loosely connected guidelines that nobody uses in the same
manner.

~~~
WillPostForFood
Maybe it is fair to call REST a failure in that it is flawed, and there aren't
perfect implementations. But I just had to go through a SOAP XML integration,
and it was ten times more painful than the worst REST experience I've had. So
I still see REST as one of the biggest tech wins in a long time.

~~~
edejong
Really? I made one yesterday based on a WSDL from a customer. The whole API
was auto generated in type safe Scala in seconds. After adding authentication
configuration and some sensible timeouts, I had the whole thing running in two
hours. The SOAPui auto generated a mock test and load tests with which I could
mimic specific weird responses.

The REST API I had to forward through however had no good documentation, no
client library, so I was forced to write json serializers and reverse engineer
the code. Overall, when you have a well written SOAP interface (rare,
admitted), development time can be greatly reduced.

~~~
user15672
Did you really just complain that REST is bad because you couldn't find an
auto-generation tool to do your work for you? Because that's hilarious.

Also, you don't seem to have looked terribly hard, because there are a few
really powerful tools out there for autogenerating server and client code for
REST APIs, as well as mock servers and a whole host of other tooling (See:
Swagger, RAML, API Blueprint for starting points).

~~~
edejong
I wonder how you arrive at your conclusions. It's rather hilarious, to be
honest. I've found that good machine readable specifications of rest
interfaces are as rare as well designed SOAP interfaces.

I've used a variety of tools to generate and test REST interfaces in the last
ten years. To a mixed success, I must say.

------
teddyh
In my opinion, you can't really understand REST until you understand HATEOAS -
the two concepts work together and REST (and the restrictions it imposes)
isn't really very meaningful without HATEOAS.

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)

~~~
stymaar
I might be unlucky but I've personaly never encountered a single REST API that
implements HATEOAS (among many third party APIs I've integrated into softwares
I've been working on on).

If almost nobody who implements a REST API has HATEOAS in mind, doesn't it
mean that REST is _de facto_ independent from HATEOAS, no matter what the
initial theoretician said about what REST should contain ?

In other words, if REST mean something different for almost everybody than
REST for the author (and a minority of people aware of the author's first
intention), then in my opinion it doesn't mean that everybody is wrong about
REST, it just mean that the word «REST» has evolved to a slightly more relaxed
definition.

This is also the claim of this talk:
[https://www.youtube.com/watch?v=6UXc71O7htc](https://www.youtube.com/watch?v=6UXc71O7htc)

~~~
masklinn
> If almost nobody who implements a REST API has HATEOAS in mind, doesn't it
> mean that REST is de facto independent from HATEOAS

If it's independent of HATEOAS what is in REST? If it's just doing HTTP, why
not call it HTTP?

~~~
stymaar
> If it's independent of HATEOAS what is in REST?

Using GET/POST/PUT/DELETE with a defined semantic, the confidence that GET is
idempotent, and the proper use of HTTP status codes.

Back in 2005, it was really common to have only GET routes even for update of
deletion, or worst: to have a single url:
[http://example.org/action](http://example.org/action) which concentrated all
the API surface, different behavior being triggered by the type of the payload
(JSON or even XML). Also, all the errors where `200 OK` but with a payload
which contained the error. It was all done on top of HTTP but nothing was
really using the HTTP tools (route + method + status code).

Every single API / webservice had its own logic & semantic, working with 3rth
party was a nightmare … It's exactly this kind of mess that the modern trend
of «non-dogmatic REST» really solved.

> If it's just doing HTTP, why not call it HTTP?

Is it really REST ? No.

Is everybody calling it REST ? Yes.

Can we change how everybody calls it ? I don't think so, and I don't really
think it matters.

Many things are poorly named[1], but as soon as it gets to the popular
language we need to use it for what it mean for people, not for ourselves.

[1] Is a «quantum leap» a nano-scale step forward ? Where is the isomorphism
in an Isomorphic web app ?

~~~
masklinn
> Using GET/POST/PUT/DELETE with a defined semantic, the confidence that GET
> is idempotent, and the proper use of HTTP status codes.

That's literally got nothing to do with REST though, that's straight out of
RFC 7231 (sections 4 "request methods" and 6 "response status codes") and the
IANA HTTP Method Registry.

~~~
stymaar
You're right and wrong at the same time:

\- Technically REST and HTTP are two different things, I totally agree with
you.

\- Historically, before REST became popular, people where doing complete
nonsense on top of HTTP, with no respect of the spec whatsoever (see my
comment above). This madness was stopped _because of REST_ ! It's only when
REST gained in popularity that people started to learn HTTP, and since then
people developed a lot of semantically valid HTTP interface and called them
REST API.

To sum up my previous points : REST as imagined by Roy Fielding never caught,
and the word REST is now almost unanimously used to describe «HTTP-compliant
API». May HATEOAS rest in peace :)

------
abraae
This article is largely bollocks.

1) Almost every gripe in it refers to bad implementations, not bad specs.

2) It doesn't even mention HATEOAS. I'm no fan, but usually arguments about
whether your API is REST or not revolve around how/whether you've done
HATEOAS.

3) The rest of it is pulp tech writing that sounds like it was vomited out to
meet some kind of publishing deadline.

Case in point:

> Consider, for example, when we might use the 200 OK response code. Should we
> use it to indicate the successful update of a record, or should we use 201
> Created?

Here's a clue - read the spec! (SPOILER ALERT: the word "Created" is the
giveaway). To quote:

200 OK

The request has succeeded. The information returned with the response is
dependent on the method used in the request, for example: <snip>

201 Created

The request has been fulfilled and resulted in a new resource being created.

~~~
weq
Spoiler alert, if the majority of implementions are "bad", or dont mention
HATEOAS then the article is totally justified.

REST will live on in memory, as an idea of a utpoia, just not in
implementation.

~~~
icebraining
Nope, the majority of implementations are just fine, and follow HATEOAS pretty
closely: they're called "websites". You're using one of them right now.

------
throwaway5752
What is it about CRUD over HTTP that drives some people nuts? A bit too much
overhead, not perfect for high performance/low level data channels, and not
perfectly standardized. But it piggybacks over a wildly popular level 7
protocol that takes care of security in a well tested way, already plays well
with proxies/load balancers, has thousands of implementations in most
languages, is well understood by network admins and usually already handled if
you're shipping software to customers. It has a lot going for it.

Sure - everybody ends up reimplementing async jobs and polling... some people
prefer XML/json/edn/etc... some people get pedantic on 3xx and non-200 2xx
status codes... differing standards on referencing other
objects/collections/etc... some people use POST where they should use PUT (or
insist upon using PATCH and OPTIONS). It has just as many faults.

But it's wildly successful for are reason, and dismissing it probably is going
to result in relearning a bunch of hard-earned lessons about integrating
across lots of very heterogeneous systems and environments.

~~~
discreteevent
It's wildy successful for a reason, which is that its primary usee is by web
browsers for document transfer. And as a result firewalls allow http over port
80 or https over 443. For a lot of cases you simply cannot communicate at all
unless you use http. The reason for its success is that there is simply no
other choice whether it's good or bad.

------
notfed
"For example, most web browsers have limited support for PUT or DELETE."

Um...is this guy trying to implement REST clients with HTML forms? Does he
know about ajax? Fact check: [http://stackoverflow.com/questions/165779/are-
the-put-delete...](http://stackoverflow.com/questions/165779/are-the-put-
delete-head-etc-methods-available-in-most-web-browsers)

------
daliwali
I think this article is a big lie, because it's based on the premise that what
is being described is in fact REST.

First, it has nothing to do specifically with the mechanics of the HTTP
protocol. There was an emergent pattern as people built APIs over HTTP, that
they can re-use much of the semantics in common with HTML. HTML over HTTP
naturally led to the definition of REST, where forms, semantics, and
hyperlinks are not just an optional feature but a necessity.

Formal specifications, meaning hypermedia API media types are just emerging,
Hydra[1] and Micro API[2] to give examples. Fielding wrote about REST in 2000
and about a decade later was rediscovered by industry, and I hope that two
decades later, people will rediscover its utility for APIs. My interpretation
is that Fielding did not "invent" REST, but rather formally described emergent
behavior on the web at large. Implementations may have differed wildly but had
many features in common.

The problems described in the article are the result of not following a media
type suited for APIs. HTML is a wildly successful media type for machine-human
interaction, there's no reason why there can't also be one or a few for
machine-machine interaction.

[1] [http://www.markus-lanthaler.com/hydra/](http://www.markus-
lanthaler.com/hydra/)

[2] [http://micro-api.org/](http://micro-api.org/)

~~~
spangry
In complete agreement here, especially your description of Fielding's thesis.
If you're looking to create an architecture that scales well and permits
discoverability, then it makes a heck of a lot of sense to examine and
formalise the properties of real-world architectures that have achieved this.

More to the point, I think the original article's criticisms are pretty
disingenuous. And his decision to ignore 'complicating factors' associated
with network transport and caching: gee perhaps you're ignoring these because
you CAN largely ignore these if you architect RESTful APIs. I mean c'mon,
stuff like this makes me think the author is either very naive or very
ignorant: _The vocabulary of HTTP methods and response codes is too vague and
incomplete to get agreement on meanings. No governing body - at least to my
knowledge - has convened to set things straight._

Yes, yes they have. Remember SOAP? That's an OASIS "standard", it's highly
specified in detail and it meets the author's desire for 'content' being
independent of the transmission channel (you know, for when you want to
implement a web API over two tin cans and a piece of string). He should just
use that, or the OASIS ratified SOAP v2 (i.e. ebms3/as4), which is also
'transport neutral'. Have fun with that.

The rest of the criticisms basically boil down to "sometimes people don't
implement it right" and "I don't understand HTTP response codes". There's
really nothing that magical about REST. When you browse the web you are
basically using a 'human-friendly' interface to a RESTful system. When APIs
use the same architectural style it's the same thing, but for robots. That's
pretty much it.

------
blablabla123
I see the point that REST is not perfect, but better than "awful". IMHO it
qualifies for pretty nice:

Point 1: 200 is shorthand for 2xx. If I'm too lazy what the code is for
"forbidden" or "insert something fancy here", I just return a 400. Does it's
job and underlines that it's the user's fault. ;)

Point 2: PUT and DELETE worked for me very well. I remember just one project
where everything had to be "tunneled" through GET. Because "exotic"
toolchain/frameworks, at least there was a canonical way to do so.

Point 3: I think that's actually the nice thing about REST that its vocabulary
is limited. Thinking about the pletora of unstructured HTTP XML RPCs and tons
of structurally different Highlevel JS APIs for each vendor, REST seams quite
relieving.

Point 4: I don't really get that. Chrome Debug works awesome, I get all the
information I need. There are many tools out there for mega comfortable
debugging.

Point 5: That's definitely a thing. I wish the article was only around that
point.

~~~
ffjffsfr
> I see the point that REST is not perfect, but better than "awful".

:+1 and they are also better than what author advocates. One thing in author
proposal that absolutely puts me off is this:

> JSON-Pure APIs (...) have only one response code to confirm proper receipt
> of a message - typically 200 OK for HTTP.

This is terrible. PLEASE do not design your API-s like this, this will confuse
the hell out of all bots, browsers and everyone who depend on status codes
(and that's all web clients). Your 404 error pages will be cached and stored
in google, redirects will not be remembered, error pages not retried, etc etc.

I don't get the idea of json pure. Author claims that one benefit is:

> All errors, warnings, and data are placed in the JSON response payload.

But REST-ful API doesn't forbid you from returning informative error messages
in json. Why not keep old HTTP semantics known by everyone and return json
with informative error message?

I also think that author confuses HTTP semantics as defined in actual WEB
STANDARDS with purely academic work of Roy Fielding. Meaning of status codes
or methods has nothing to do with REST-ful this is just plain HTTP semantics
as defined by RFC-s.

------
eranation
Sorry for the controversial question, and I probably raised my eyebrow if I
saw a candidate choose XML over JSON when taking on a recent project... but
really, why JSON? No comments, no multiline, no schema. I understand that XML
is bad because ____ (not cool, verbose, old school, only enterprises use it?)
I am not a huge YAML fan but it seems this is the only human readable form of
JSON. The lack of self describing human readable scheme is mind bugling. So
SOAP and XSD is bad (?) so instead we got swagger (?) is it really better?

Was ditching XML for JSON just due to cosmetic / trending reasons?

We still use HTML for markup. Why did everyone ditch XML for JSON beyond just
treading reasons is an interesting question.

~~~
kowdermeister
> but really, why JSON? No comments, no multiline, no schema

Limitations are good. I find it really easy to read. You can install browser
extensions to make it even more readable.

Schema can come from a well written specification.

> Was ditching XML for JSON just due to cosmetic / trending reasons?

No, as said before, it's easy to write / read / generate / parse. No awkward
DOM style management if you want to parse out a value. I really hated it with
XML.

HTML is fine also for what it was invented for.

~~~
masklinn
> You can install browser extensions to make it even more readable.

Most browsers can display XML readably by default.

> Schema can come from a well written specification.

That doesn't replace a schema though.

> No, as said before, it's easy to write / read / generate / parse. No awkward
> DOM style management if you want to parse out a value.

"DOM-style management" of XML documents which can be replaced by JSON is
equivalent to hand-rolling a JSON parser from the raw bytes. It's not the
hardest thing in the world, but it's not exactly easy either.

With most XML applications equivalent to JSON, that part would be tucked away
in the relevant library, e.g. the XML-RPC serialisation format is almost
isomorphic to JSON[0], and in Python converting between native objects and the
XML-RPC serialisation is just `loads` and `dumps`[1] — though you don't
usually have to do that at all since the XML-RPC client will handle the
serialisation and deserialisation for you automatically — which is more or
less what the JSON library provides[2].

And JSON is convenient in dynamically typed languages because it maps more or
less directly to their native dynamic structures, that's not quite the case
for languages like C++ or Haskell.

[0] null (nil) is an extension but it natively supports binaries and datetimes

[1]
[https://docs.python.org/3/library/xmlrpc.client.html?highlig...](https://docs.python.org/3/library/xmlrpc.client.html?highlight=xmlrpc.client#convenience-
functions)

[2]
[https://docs.python.org/3/library/json.html?highlight=json#b...](https://docs.python.org/3/library/json.html?highlight=json#basic-
usage)

~~~
kowdermeister
> Most browsers can display XML readably by default.

True, but a JSON string is already more readable than XML.

If you open your devtools it's inspectable by default:
[http://imgur.com/a/eW0Rv](http://imgur.com/a/eW0Rv)

> that's not quite the case for languages like C++ or Haskell.

So handling XML in those languages are easier?

BTW if your server / services feel more native with XML serialization /
parsing to native data structures use that. Picking JSON just because
everybody else does it is not a good idea.

However if you make a public web API consumed mostly by browsers (JS), then
yeah, pick JSON and REST.

~~~
masklinn
> If you open your devtools it's inspectable by default:
> [http://imgur.com/a/eW0Rv](http://imgur.com/a/eW0Rv)

That also works for XML documents:
[http://i.imgur.com/NmcWdaO.png](http://i.imgur.com/NmcWdaO.png)

> So handling XML in those languages are easier?

Both are "crap" since they're dynamic information which has to be brought into
a statically typed world. However depending on the schema it might be possible
to automatically generate the binding and hide the dynamic resolution.

> BTW if your server / services feel more native with XML serialization /
> parsing to native data structures use that. Picking JSON just because
> everybody else does it is not a good idea.

> However if you make a public web API consumed mostly by browsers (JS), then
> yeah, pick JSON and REST.

Agreed.

------
awinder

      Ever notice how nobody calls their API “RESTpure”? Instead
      they call it “RESTful” or “RESTish”. That’s because nobody
      can agree on what all the methods, payloads, and response
      codes really mean.
    

These reasons have nothing to do with why people don't use the term "REST"
versus using "RESTful". RESTful is the compromised approach, cribbing some of
the concepts outlined in Fielding's paper but dispensing with others. Among
those are a de-emphasis of linking, and a url naming pattern. HTTP verbs
describe types of actions in RESTful lingo, versus meaning something about the
different idempotency & safety guarantees of a request in the REST paper.

In REST, I'm not sure that a lot of these issues are that contentious. I do
think that some of the emphasized points in "RESTful" design practice can
create more contention in API design, but that's the downfall of that one
pattern, it has nothing to do with what Fielding described.

    
    
      No governing body - at least to my knowledge - has convened to set things straight
    

IANA has a ton of info on link relations and they're thoroughly speced. IETF
has tons of API / REST related specifications. Profiles allow for defining
what your data means, there's open source curated lists of these profiles
already so if you were designing an API you could even leverage existing works
to make your design easier.

    
    
      Roy is probably a great guy and he certainly had a lot of
      great ideas. However, I don’t believe that RESTful APIs was
      one of them.
    

This statement is just downright hysterical given the relative disparity here.
So much of the web is owed to Fielding's paper, there's been countless books
and blog posts and just human man hours devoted to the work he's done. Who's
this guy? Why is this such a trend in blog posts in this community, it just
looks foolish and comes off as petty...

~~~
ianai
How accurate are those curated lists?

------
debaserab2
Most of the problems described with REST in this article are examples of REST
implemented improperly. We've had years to get it right; things like HTTP verb
support, debugging, discoverability are all by and large a solved problem. The
one point that stands is that it is deeply tied to HTTP, but I consider that
to be a positive: a well designed REST API means the message is only about the
content of what it's serving and not about negotiation of that content.

Here in the "JSON Pure API" you see a reinvention of HTTP request and response
concepts built into the API payload, leaving the implementation of negotiation
up to the consumer of the API. You lose all the benefits of years of
development that have gone into browsers and web servers to handle this for
you.

The main problem with REST is that people tend to call any JSON endpoint they
build a REST API (and hence the term, "RESTful") which leads to a
misunderstanding of what REST actually is.

~~~
psadauskas
Right, there's a great many blog posts that can be TL;DRed as "We implemented
REST wrong, and it didn't work. I guess REST is overrated."

There's two major components that makes an API truly REST, as opposed to the
XML-RPC and SOAP-style APIs that were popular in the early 2000s: Proper use
of the HTTP verbs, and the use of Hypermedia.

Most so-called RESTful APIs have adopted the verbs part of it successfully and
correctly, but the vast majority have completely whiffed on hypermedia.

Your HTTP API is a state machine whether you like it or not. Hypermedia gives
you a means to describe the state transitions as a part of your API. Without
it, you are essentially requiring each of your API consumers to re-implement
the state transitions for themselves. (The aggravating part of that, however,
is that there's not too many good hypermedia-based client libraries, because
it seems that most of the proponents would prefer to navel-gaze in their ivory
towers, thinking about RFCs and getting the standards perfect. But I digress.)

I wrote a blog post a few months back that goes into more detail about the
advantages conferred by a true Hypermedia API:
[http://blog.theamazingrando.com/in-band-vs-out-of-
band.html](http://blog.theamazingrando.com/in-band-vs-out-of-band.html)

~~~
int_19h
I'm not sure I see the advantages. It's a _lot_ more verbose, based on the few
examples I'm seeing there, and strongly reminds me of SOAP, XML Schema, and
the rest of that over-complicated stack.

I suppose some amount of complication would be fine if the benefits were
clear, but I feel like I could implement a client and a server for the less-
verbose API that you start with, in the amount of time it would take to
implement a server alone with all those bells and whistles. And I can't think
of any scenario where they would actually add value.

I think the reason why RESTful APIs with very simple JSON payloads became so
popular is because they get the job done with so little effort and so few
abstract concepts to grok. This feels like a step backwards in that respect.

------
Mandatum
I think the first comment/reply to the post hits the nail on the head, by
Florian Klein[0]:

> Awesome! You replaced REST with REST. How revolutionary:

> Instead of transferring application state through the wire via one of its
> representations, > you know transfer its state through the wire via one of
> its representations.

> Do I need to go any further? > I think so, because to me your confusion
> comes mainly from the vocabulary you seem to misinterpret. You didn't even
> talk about hypermedia or links! That's kinda strange in an article about
> REST.

> Even tho I agree this vocabulary can be confusing, you should not throw the
> stone on the wrong subject (REST). > Your problem is HTTP, right?

> Rest is not tied to http at all, and your point about making response bodies
> self contained is an honorable idea, but it doesn't change __anything __to
> your application being RESTful or not.

I work building, debugging, deploying and integrating JSON-formatted RESTish
web API's every day. I find purist API's to be the most painful to use, and I
find people who take the this-is-pretty-much-RPC-over-HTTP approach to be the
second most painful unless it's perfectly built for my use-case.

There is a perfect middle-ground for most API implementations and really it
comes down to the architects and software engineers implementing the API being
able to think like API consumers and thinking of most use cases for their
API's up front, then having a good level of "80% of people will use it this
way, so we'll try and cater to the masses but support the other 20% like
this".

There are definitely the marketing types who sell REST as the be-all-end-all
solution to APIs, and all the other bells and whistles that go along with it.
That isn't unique to REST.

I'm not on a mission to appease 100% of all use-cases for an API or
integration. Such a solution will never exist and people trying to make out
like there must be some sort of "holy grail" of API definition and design out
there and %insert_current_fad% is wrong! No. We're doing our best, and today's
API's with their API Test Consoles and their interactive walk-through's for
people new to the API are a hell of a lot better than what we had before.

[0] [http://disq.us/p/103w6z6](http://disq.us/p/103w6z6)

~~~
anentropic
What are the problems you tend to encounter with purist REST APIs?

------
imafish
_> most client and server applications don’t support all verbs or response
codes for the HTTP protocol. For example, most web browsers have limited
support for PUT or DELETE. And many server applications often don’t properly
support these methods either._

I have never, as in ever, stumbled upon this problem. So I googled it. It
turns out that what he means is that HTML forms don't support PUT and DELETE.
In a world where everybody uses JavaScript anyway, I cannot see how this is a
flaw in RESTful API's. It might be a flaw in HTML forms though.

~~~
abraae
To be fair, the verbs can feel a little weird.

GET is easy.

HEAD is easy.

DELETE is easy.

PATCH is easy, especially when you use one of the two more useful standards
(RFC 7386: JSON Merge Patch, or RFC 6902: JSON Patch).

PUT is not much use for large resources (like those typically found in
business systems) since it requires you to provide _every_ field, but usually
you would want the back end to assign at the last the primary identifier, date
created, etc. I seem to remember reading that even Roy felt PUT was not well
designed.

POST is a catch all for any other update/insert type activity.

To paraphrase Winston Churchill, "http verbs are a poor system, but better
than all the other systems that have been tried from time to time."

~~~
martin-adams
When you say you want the server to assign the identifier and additional
fields, then I guess this would be considered read-only metadata against the
resource. I don't recall seeing anything stating that in my RESTful travels.

~~~
abraae
Read-only or not, its still part of the resource, and so PUT must supply it.
Here's a nice writeup: [https://stormpath.com/blog/put-or-
post](https://stormpath.com/blog/put-or-post)

------
ravibala1
Seems like most of the comments hate on REST because it's been poorly
implemented by an API developer. Why is the solution yet another API protocol
(JSONpure) and not stricter enforcement? (Idealistic i know...)

The point about SOAP not requiring documentation makes no sense either. You'd
still need to document what the underlying fields in the various endpoints
are. (We build against a lot of terribly documented SOAP APIs and its pure
torture)

In terms of PUT (and PATCH) not being extensively used - it comes down to your
use case. For the idempotent micro-services we build APIs against, there is a
massive difference in the behavior expected for POST/PUT/PATCH and it would be
pretty burdensome (and limiting) to have to create parsing code on the server
for POST.

------
rs86
I liked that the article made me think of using websockets for a pure JSON
API, but I think it misses a lot of what is nice about rest and much of what
it criticises is actually HTTP..... Rest as a set of verbs that act on
resources is really useful.

I used to find it awkward to implement services in rest, as in some action
that is triggered and may overlive the request cycle until I started thinking
of service commands as items in a work queue that get processed by a worker.
So when a service is requested I can see it as a resource being created.

------
Animats
From the article: _" The way forward: JSON-Pure APIs"_.

I can see a little of this. It's better today to send parameters in HTTP data
in JSON format rather than encoding them in the URL. If you're doing a pure
GET, you can send parameters with the URL, but anything that changes server
side state probably shouldn't be done that way.

Of course, what's happening is that the JSON crowd is re-inventing SOAP, but,
whatever.

~~~
masklinn
> Of course, what's happening is that the JSON crowd is re-inventing SOAP,
> but, whatever.

SOAP uses schemas and the like, they just keep reinventing the same RPC as
ever, except can't actually bring themselves to use the word. At least JSON-
RPC is honest there, and ticks all of TFAA's box:

* uses whatever's under as a trivial transport (covers 1, 3 and 6)

* all data and metadata are part of the higher protocol (covers 2, 4 and 5)

* is JSON (covers the entire essay)

~~~
sandythos
Hence also reinventing CORBA IIOP, DCE, Apollo NCS, Xerox Courier...

Actual innovation in this area seems to be limited to JS background data sync
libs. Ironically, reference-capable protocols like CORBA anticipated this
whereas flattening it all REST-style was a step backwards.

------
agentultra
I think REST is a perfectly acceptable and well-adopted pattern. There's no
lie to it. I think GraphQL _could_ displace it but adoption will be key.

What I am sick of with REST APIs is having to code them from scratch in
dynamic languages each time and hook up all that laborious plumbing!

I read in an O'Reilly book on the subject that good REST APIs are declared. To
that end I've been looking to tools like PostgREST, PostGraphQL, Swagger, and
the ill-named Servant. Define the data, declare the resource routes, and
you're good to go; generate the server stubs, the client code, and the
documentation from the specification.

You don't get that from adopting a new standard every few years.

------
bradmwalker
REST: JSON CRUD over HTTP
[https://youtube.com/watch?v=oVE6OF-d1oQ#t=02m02s](https://youtube.com/watch?v=oVE6OF-d1oQ#t=02m02s)

------
apo
> REST became popular when it was detailed and promoted by Roy Fielding as
> part of his doctoral dissertation entitled Architectural Styles and the
> Design of Network-based Software Architectures in the year 2000. Roy is well
> known for his contributions to development of the web, especially the HTTP
> specification.

So far so good.

> Roy advocated using the request methods he helped define in the HTTP
> standards to impart meaning to HTTP requests.

Not even close.

REST may be one of the most misunderstood ideas in all of computer science. As
described in Fielding's dissertation, REST is a software architectural style
whose main idea is that hypertext drives state changes, aka Hypermedia as the
Engine of Application State (HATEOAS). Fielding leaves the transport protocol
as an implementation detail.

In other words, an automated agent (API consumer) should interact with an API
in the same way that a human interacts with a Web site. User browses to well-
known URL. Page displays content with links. User clicks on a link. And so on.

A human doesn't need to read documentation on using any particular website any
more than an automated agent should need to carry service-specific
instructions on using an API. Media types and hyperlinks do all the heavy
lifting.

The stuff about structured URLs and response codes came later, was created by
others, and has almost nothing to do with REST's central idea. It's a
different architectural style altogether.

From Fielding himself:

> I am getting frustrated by the number of people calling any HTTP-based
> interface a REST API. Today’s example is the SocialSite REST API. That is
> RPC. It screams RPC. There is so much coupling on display that it should be
> given an X rating.

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

------
tobyjsullivan
On first pass, I totally agree with the author. I haven't reviewed the
proposed alternative yet but fingers crossed.

That said, I think he misses the single biggest issue with REST APIs that I
continuously encounter and which has caused me to consider them sub-par.
Representative "State" Transfer. REST APIs are only good for transferring
around the state of stateful objects.

However, CRUD operations are only part of the equation in most modern
software. Much of what we do is performing actions on those stateful objects
(or, better yet in the microservice world, avoid state altogether). REST
provides no identifiable mechanism for performing actions outside of CRUD
operations and is, therefore, a completely impractical solution. Most real
companies' attempts to build a "RESTful" API just end up being RPC over HTTP
dressed up to look like REST.

~~~
icebraining
_REST provides no identifiable mechanism for performing actions outside of
CRUD operations and is, therefore, a completely impractical solution._

The mechanism is identifiable once you start to really think in REST terms.
The problem is that people think in RPC, and so try to shove its model
instead.

REST is based on names (resources), not commands. Therefore, we must implement
our actions as resources. Instead of having a "transfer()" command, you have a
Transfer resource _type_ , which you create to start one. Eg:

    
    
      POST /transfers ... (Body describes parameters)
      201 Created, Location: /transfers/34
    

This change from a command to a resource additionally provides the benefits of
REST, necessary for communication over an unreliable network: rather than keep
your connection open while the action is processed, you get an URL you can
poll to check if it is finished. This works even if the client goes offline
for some time.

~~~
icebraining
To add to my previous post: it's not like this is a weird concept; every
e-commerce site out there implements this. Imagine if we followed the RPC
model: the user would click on "submit", and then the browser would wait for a
reply when the order was finished being delivered - multiple days later!

Obviously this is impractical, so people follow the natural REST model: they
create an Order resource, then send you a link with which you can follow the
status of that resource.

But bring the "API" word and suddenly all of the preconceptions push
developers to implement everything as function calls.

------
gkoberger
The promise of APIs is simple. Send some data, something happens, get some
data back.

But at about hour 4 of wrangling a bearer token to authenticate your barely-
documentated PATCH request that is returning a strange error about your
application/x-www-form-urlencoded body, you start to realize that APIs in
theory are very different from APIs in practice.

(That being said, I don't love the "solution". It's very simplistic and it
seems like the author doesn't really understand what he dislike about APIs. I
don't think we need another protocol, but rather higher-level tools for
dealing with them.)

------
jondubois
The author seems supportive of the core principles behind REST but arguing
against its specific implementation in HTTP.

I wrote a related article for Hacker Noon a few days ago which was trending on
Reddit: [https://hackernoon.com/rest-over-websockets-instead-of-
http-...](https://hackernoon.com/rest-over-websockets-instead-of-
http-81b0f0632295)

It's interesting that an increasing number of developers are pushing the
notion of using REST-like ideas over WebSockets instead of HTTP.

------
madhadron
I've never actually seen a REST API in practice, just HTTP APIs, by which I
mean I've never seen a fully hypertext driven interaction with data. Let me
sketch what I would expect that to look like.

I fetch from a URI
([http://example.com/meep/boris](http://example.com/meep/boris)) and get back
a response with Content-Type application/meep; version=3. My browser searches
for a viewer for that content type. The content type defines the actions I can
take on the content, either locally or talking to the server, just as it does
for any other protocol passing data over the wire. That understanding has to
be out of band for the model.

But to be truly RESTful, the viewers must also be accessible via hypertext.
For example, the response with the content could include a link header to
point me to a usable default viewer for the content type. So you have to have
a content type that whatever you're using (browser, SPA in the browser, etc.)
knows how to interpret as a handler for content types. Whether it uses PUT,
PATCH, or BABOON in HTTP verbs should be irrelevant. That's part of the
protocol of the content type handler.

It's that second part that's a problem. The security implications are a bit
worrisome. And if you're shipping handlers only for your own data, you control
all the pieces, so there's no point going through all the decoupling.

------
fleitz
Here's the rub, you're completely right, the problem is for the most part when
you don't have rockstars making JSON Pure APIs you end up with half of HTTP
redone in some god awful manner.

I once worked with an API where they implemented their own HTTPS and because
their own https didn't support gzip they removed quotes from json keys to save
bandwidth. JSON pure probably is better when working with knowledgeable people
but REST is better than what most people come up with and when not following
REST

------
Manishearth
> Ever notice how nobody calls their API “RESTpure”? Instead they call it
> “RESTful” or “RESTish”.

Isn't that just because RESTful is a play on words?

> For example, most web browsers have limited support for PUT or DELETE.

Really? How? If anything browsers restrict these methods to exactly how they
should be used (DELETE can't have postdata but PUT can).

It's true that folks don't use PUT/DELETE much (the alternative works
perfectly well though), but to me that's because they're unnecessary
complexity, not browser support.

------
sebringj
Relating to this...recently I needed to hook up a web app to a JSON RPC API
and also extend that API, having to work with a legacy system. It was
interesting to note that there was only one POST verb used in the entire API
and the data format was always the same. At first I grumbled and was annoyed
by the use of this system as it was old as hell but after some point, I was
like, "oh, i don't have to worry about verbs now" or where to grab from
params, query string, headers or body... so it was actually easier. I still
hated it though because it wasn't REST because I was pretty biased with the
status quo.

What I'm trying to say is having more choices or more ways to do something
isn't necessarily a good thing as it makes it easier for people to do it so
many ways that they can screw it up or just make it weird for everyone else.
REST is kind of weird that way and I agree with this article for the most
part.

------
weixiyen
New mobile-first products should consider GraphQL over REST. There's a lot of
benefits that you will probably end up doing yourself in a bastardized version
of REST anyways, like field restrictions and multiplexing multiple unrelated
data requests over the same network call.

GraphQL handles these cases elegantly.

------
jaequery
I think there are two types of developers. Pragmatic ones that puts focus on
making things better/easier, and then those who generally don't give a shit,
as long as they have some kind of standards to go by. Pragmatic ones are the
ones who comes up with new frameworks, new languages, new standards. The rest
are, sort of like sheeps. And we are all sheeps at some point. It's just a
problem when the sheeps have a problem with someone trying and coming up with
a new thing.

So when I see a blog article like the author, I think we should just hear him
out, get what you can get out of it and either support him or let him be.
Sure, he may not be perfect but at least he has tried scratching an itch where
he saw a potential problem and looked for a solution. And the problem he has
is actually shared by thousands of developers so he is definitely not alone.

Every couple years (hell, every couple months now), we face some new
technology, or some new way of doing things and there is always the initial
set of people who come across as being highly offended by it.

Like back in the days when XML was all the hot stuff and when JSON came out,
most bypassed it stating it's not sophisticated enough, doesn't have any xpath
support, bla bla bla, doesn't have a reference book must be not ready for
enterprise. It was the same thing with SOAP when REST first came about. And
these type of patterns repeats throughout the years, from frameworks,
languages, and probably everything else.

People hate change. I think we all get that, it's just the way it is. However,
over time the same people that were against it, slowly gives in to the same
thing they were against the more people start talking or hears about it. I'm
sure it happened to you at some point.

So folks, don't just judge a book by it's covers. Give it some time and
perhaps even give it a try. RESTful may be good as it is for you now, but I'm
sure you also know that it is not as good as it gets. There are those who
believes there are problems with the RESTful approach we have now and looks
for a new standard that solves them. They may be right and perhaps will come
out with something we will all be using some day. Who knows.

------
INTPenis
I've developed both REST and XMLRPC API's. The right tool for the right job.

Sometimes REST is that tool.

I also tend to combine JSON with REST. I still enjoy using proper HTTP codes
when possible. So if you're sending a json payload to update an object that
doesn't exist I'll give you 404. But at the same time you're able to create
that object by defining its properties in a json payload in the next request
and not some obscure url parameters or POST parameters.

I don't see anything wrong with using proper HTTP methods and return codes
when possible.

------
jquast
I think what bothers me most about REST is that the endpoint is not sufficient
to get started. The schema is never known. I hate SOAP and xml-rpc, but at
least you can know for sure what endpoints, parameters, and variable types are
appropriate. With REST, you _must_ have documentation or source code of the
service you communicate with, they offer no discoverability.

I won't use REST again. I got an opportunity to use GraphQL recently in my
profession and all of my projects will be using it in the future.

~~~
dragonwriter
> I think what bothers me most about REST is that the endpoint is not
> sufficient to get started. The schema is never known.

If you are actually doing REST, the interpretation of a resource
representation is fully specified by the media-type (insofar as if there is
additional schema, etc., information necessary, how to find that given the
actual representation is also defined by the media type.)

Obviously, this is not true in the all-to-common REST-minus-HATEOAS.

~~~
djsumdog
You can sprinkle links/rel and use custom/vnd mime types (and include links to
the correct json or xml schema) and then a developer can figure out how an API
works just from an endpoint, yes ..

but that's not what this person is saying. The thing about SOAP is that it is
very concrete and a standard. Yes you get implementation glitches/bugs here
and there, but for the most part, you have a standard definition for an object
and a standard way to describe it.

It's so standard you can point a debugging tool like SoapUI at it and it will
construct a nice little form for filling out all the objects you want to pass
with the correct types.

There are other terrible things about SOAP and it's difficult to version/add
functions/update/blah blah, but it was concrete.

You could create tools to auto-discover all the paths in HATEOAS
implementations, but it's still not quite as concrete as SOAP. Most people
don't and rely on documentation to build clients with the right
schema/requests/types. REST/HATEOAS are concepts and you document your
formats, marshallers, etc. SOAP/WSDLs describes the entire data-interchange in
a much more concrete format.

As much as I hate SOAP, I wish we had a more concrete interchange standard
that wasn't as terribly complex.

~~~
elcritch
Swagger is a decent middle ground. There's a lot of warts, but it's
serviceable and fairly prevalent with implementations in a variety of
languages. Mainly I like to use the yaml version to quickly communicate rest
api's. I've also recently started appreciating JSON Schema more recently for
this reason. It's lighter weight than xml schemas. Inclusion of regex based
field validation is pretty handy.

------
AngeloAnolin
Did I missed something on the article, whereas, I was hoping that it would
expound on why REST should not be trusted. A title more apt would be:

"REST is totally flawed" or something similar.

Saying REST is a big lie is somewhat misleading, when the overall context of
what it is and what it should be is still up for debate.

Does it matter when you can't completely and fully define what REST should be,
but you are out there building awesome products while the rest of the web
world is still up in arms on what it has to be?

------
lliamander
I think this article actually misses some good criticism of REST that I've
encountered over the years: \- how do you perform queries across resources? \-
how do you perform actions that don't map to CRUD actions (e.g. tell a server
to reboot itself) \- how do you perform actions that are transactional across
resources?

I'm not saying there aren't answers to these questions, but doing any of these
things in REST is not straight-forward.

------
weq
As everyone else points out, GET and POST are really all thats implemented in
anything else other then a catelogging system.

So if we concede that people using these 2 operations are not implementing
REST, what are they implementing? Well i would argue, CQRS.

GET = Query, POST = Command

Then our REST api becomes super simple and consistant across implementations.

/api/run POST UpdateModelCommand { } /api/run GET ListModelQuery { }

------
deathanatos
This article is a complete strawman. His description of a supposed "REST"ful
API is the least RESTful API I've seen in a while:

> _The what-we-actually-indended-to-use request method embedded in the request
> payload, e.g. DELETE_

Don't do this.

> _The what-we-actually-indended-to-use response code embedded in the response
> payload, e.g. 206 Partial content._

Don't do this!

> _If you’ve ever worked with a RESTful API, you know they are almost
> impossible to debug._

You're begging the question.

There exist _plenty_ of APIs that abuse the HTTP methods and status codes,
which I feel like is really the core argument being made. But completely
ignoring it and what its purpose is is throwing the baby out with the
bathwater. Read and understand the RFCs for HTTP, for a start; unfortunately,
I'd wager that far too many devs of ostensibly RESTful APIs do not do this,
and it shows when you get a response with a status code that makes zero sense.
The vast majority of HTTP APIs I've interacted with violate both the semantic
meaning of the methods and that of the status codes. (GitHub's is about the
best I've ever seen.) A "RESTful HTTP API" is an API that uses the mechanisms
in HTTP to accomplish the ideas of REST; (i.e., I'm not trying to equate HTTP
and REST, I just think abuses of HTTP are a major impediment to understanding
REST. Using HTTP well will naturally help you accomplish REST.)

> _can anyone out there explained to me what 417 Expectation failed really
> means?_

You've not read and understood the RFCs for HTTP. 417 Expectation Failed is
obvious if you have; an expectation (on the request) failed (cannot be met by
the server). An "expectation" is denoted on the request through use of the
"Expect" header. The only existing expectation is 100-continue. Even if you do
not know this by heart (and I don't expect that), it's _readily_ findable:

1\. Google "http rfc status codes"; unfortunately it's the second result;
Google doesn't understand that the second result is an updated version of the
first. Regardless, if you go for the first result, it points you to the second
(-ish, b/c the RFC was split into multiple).

2\. You select "417 Expectation Failed" in the Table of Contents.

3\. You read the extremely straight-forward explanation. If you don't
understand what the Expect header is for, the RFC links you to it.

So what are the ideas of REST? Start at its (de-)acronym: "Representational
state transfer". That is, transfer of _a resource_. A "resource" is just an
"object" or a concept, a thing — the actual concrete thing represented by a
resource is going to be determined by your domain specific problem. E.g., "a
user's profile data", "a message in a thread", "a news article" are all
"resources" in that they embody some concept or idea that we want to
communicate the underlying state of. You also need a standard, or _uniform_
method of uniquely identifying, or _locating_ these resources, which is what a
URL is for (you then see why it's lit. uniform resource locator). So we build
URLs to stand in as names for resources.

In order to transfer the state of a resource, embodied at a URL, you need to
send it across a wire. You need to serialize it into some _representation_
that's going to get transferred. That's what HTTP is supposed to help you do.

If you _were_ writing a RESTful API, embedding things like the status of the
operation in the response body should feel wrong, because the status isn't
conceptually a part of the resource you were trying to operate on in the first
place; go back to our example of "a post in a thread" — whats a status got to
do with that? While technically, yes, HTTP's entity body is capable of
transferring arbitrary binary data, the end result of using it that way
results in simply the re-invention of wheels, such as needing to signal the
success or failure of operations on resources. HTTP's purpose, alongside the
ideas of REST, is to pull out the common bits that occur when writing code
that transfers representation of stuff around, such as, e.g., caching, getting
an ok to transfer large content prior to writing it all out to the wire,
knowing the status of the operation, or pagination of collections of
resources. (I cannot count the number of times I've witnessed API designers
reinvent pagination, badly!)

The manner in which people like to use HTTP, with effectively only GET and
POST ( _maybe_!) is more akin to RPCs to me. It works. You can do that. But
you then need to handle caching, pagination, status of operations, etc. on
your own, and you'll end up, I believe, reinventing HTTP. Doing a lot of that
(I think, and I think this was Roy's original point) is more effective if you
structure your operations around transferring representations of resources
around; this is especially visible in caching, because in caching you _need_
the representation of a resource, because that's what a cache works with by
its very nature. (As opposed to, say, making opaque method calls on a remote
instance.)

Go read [1]; nothing really in there is bound to HTTP, just that HTTP makes a
lot of it easier. Also, while I understand that Roy has a lot of arguments
around how representations should be hypertext — and I agree with them, mostly
— I think that comes _second_ to the ideas that:

1\. A URL represents a resource

2\. The point of GET / PUT / DELETE is to transfer the state of that resource.

If you don't understand those two points, I don't think you'll understand the
arguments behind hypertext.

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

The other points,

> _They are easy to debug since transaction information is found in easy-to-
> read JSON inside the payloads using a single, domain specific vocabulary._

Pushing everything into an opaque blob removes the ability for any tooling to
pull out high level information. Chrome devtools, httpie, etc., all disprove
this point.

> _Problem #1: There is little agreement on what a RESTful API is_

I agree. I also feel like too many people who think they know have not read
anything from Roy Fielding, or even the HTTP RFCs.

> _The REST vocabulary is not fully supported_

depends mostly on

> _most client and server applications don’t support all verbs or response
> codes for the HTTP protocol. For example, most web browsers have limited
> support for PUT or DELETE. And many server applications often don’t properly
> support these methods either._

This isn't true: JavaScript in all browsers in respectable use supports this;
Android and iOS fully support HTTP; most server-side development languages
have excellent tooling for this. This is a completely false statement, and
requires proof, or at least a concrete example to back it up. (Were it true,
it only invalidates the use of HTTP as an aid to accomplishing REST.)

> _Problem #3: The REST vocabulary is not rich enough for APIs_

POST is, essentially, a catch-all for odd operations not supported by other
verbs.

> _Imagine we create an application where we want to send a “render complete”
> response back to an HTTP client_

If we have a resource that represents a rendering job, if you GET a
representation of that render job, it can include some indication of
completeness. The bigger problem here is actually HTTP's polling, IMO.
Websockets might serve _this specific example_ better, but this singular
example doesn't invalidate that most web APIs boil down to CRUD $object of
$type, which HTTP supports phenomenally well.

> _Problem #5: RESTful APIs are usually tied to HTTP_

Well, yes. At the end of the day, it _has to be tied to something_. HTTP is a
pretty good something, with decent tooling.

> _They use only one response code to confirm proper receipt of a message -
> typically 200 OK for HTTP._

Yes, you can send a single bit back. HTTP attempts to be a bit more rich than
this. E.g., if something is in progress, and attempting to retrieve the data I
just stored will fail until some serve-side job is complete, HTTP can easily
signal this. Muxing them into 200 OK removes that information.

> _They completely separate the response content from the transmission
> mechanism. All errors, warnings, and data are placed in the JSON response
> payload._

HTTP already has this: the response content is the body of the response. The
transmission mechanism is HTTP. I don't want errors, warnings, etc., in the
payload, where they are opaque and unusable by common tooling.

> _They can easily be moved or shared between transmission channels such as
> HTTP /S, WebSockets, XMPP, telnet, SFTP, SCP, or SSH._

These channels do not support transferring the state of something. (Okay, HTTP
does.) telnet is a mostly dumb pipe, same for SSH. You would need to build
some custom, non-iteroperable layer on top of that. HTTP is the standardized
version of that.

------
mcguire
Mmmm. Multilayered multiplexing.[1] Yay.

[1]
[http://128.232.0.20/teaching/0809/DigiCommI/tennenhouse1989l...](http://128.232.0.20/teaching/0809/DigiCommI/tennenhouse1989layered.pdf)

------
kickingvegas
So much of my confusion is mapping POST and PUT to CREATE and UPDATE, which
I've always felt was an arbitrary semantic decision. Why the unambiguous words
CREATE and UPDATE are not used in the HTTP spec as method names is beyond me.

------
toadkicker
In the second article the author explains what a 'JSON pure' api would
function. It completely throws out the OSI model and provides no way for the
application layer to react to transmission errors, which HTTP codes provide.

------
davidhariri
The author has some good points, but they're drowned in exaggeration and
dogma.

------
cxromos
This is kinda SOAP in JSON.

------
metafunctor
The proposed way forward appears to be just discarding all of the common,
reusable, standard forms we have started to build with HTTP.

JSON-Pure is not much more than an encoding. RESTful is an entire protocol.

------
isuckatcoding
As the first comment in the article mentions, this guy just replaced REST with
REST. Nothing revolutionary. I thought he was going to talk about some rpc
mechanism or something.

------
staticelf
I think what this person is looking for is basically
[https://jsonapi.org](https://jsonapi.org) or similar.

------
ads1018
(ahem!) graphql

------
FourierT-form
Isn't this just an argument for a JSON based SOAP API?

------
snambi
Agree totally. REST is hard to work with and very confusing since every
application does it differently. I have seen applications returning HTML
response for errors cases. REST is better than SOA or CORBA, but we need
something better.

------
elastic_church
(2015)

but timeless

------
robzhu
Like other posters have said, the author appears to be pointing out
shortcomings with HTTP, not REST. Roy Fielding made it fairly clear that REST
is not strictly associated with HTTP. REST, as an architectural style, is
defined by a set of constraints:
[https://en.wikipedia.org/wiki/Representational_state_transfe...](https://en.wikipedia.org/wiki/Representational_state_transfer#Architectural_constraints).
Anything that meets these constraints is considered "REST". Most of the
constraints sound like common sense for API design, and where most APIs are
disqualified from being truly "REST" and merely "RESTish" is in trying (or
not) to fulfill the Uniform Interface/HATEOAS constraint: that the client
dynamically traverses information and operations from one resource to another
via hypermedia links.

Interestingly there's yet a deeper problem with fully RESTful APIs (Hypermedia
APIs), where REST's Stateless Protocol constraint combined with HATEOAS
creates an API where clients need to undergo multiple HTTP round trips to load
the data they need. For example, suppose your app lets users browse movies.
You might have a sequence like:

client: "hey, I'm gonna act like a browser and hit api.com and take it from
there" GET api.com => { "movies": { "rel": "content/movies", "href": "/movies"
} }

client: "hmm, ok I guess I'll click the movies link" GET api.com/movies => {
"items": { "count": 4, "prev": null, "next": "/movies/page/2", [ {"href":
"/movies/1"}, {"href": "/movies/2"}, {"href": "/movies/3"}, {"href":
"/movies/4"}, ] } }

client: "ok, I guess I'll fetch each of those movies (I kinda wish the server
had just told me what those contents were in the first place)" GET
api.com/movies/1... etc. => { "href": "/movies/1", "rel": "self", "title":
"Waterworld", "image": "/images/waterworld.png", } ...

And don't forget the client-side logic to join/order all this data and handle
errors. This problem is called "underfetching" and it's present in true REST
APIs by design. Ironically, many "RESTful" APIs break from the REST
constraints specifically to avoid this problem.

Another great article on REST APIs:
[https://martinfowler.com/articles/richardsonMaturityModel.ht...](https://martinfowler.com/articles/richardsonMaturityModel.html)

~~~
u801e
> Roy Fielding made it fairly clear that REST is not strictly associated with
> HTTP. REST, as an architectural style, is defined by a set of constraints:

Out of curiosity, do you know of any examples of RESTful APIs that use a
protocol other than HTTP (say like IMAP or NNTP)?

~~~
camus2
He isn't going to provide you an example because there is none meaning full in
production. REST uses HTTP because it makes no sense to use it with anything
else. REST only makes sense with HTTP. With another socket protocol, there is
no need to bother with headers and co.

~~~
robzhu
You're right, there are no other protocols at nearly the scale of HTTP that
use REST. I was just pointing out that REST was not strictly associated with
HTTP in Roy Fielding's definition. If you look at my other link (Richardson
Maturity Model), you can see that RPC-over-HTTP is vulnerable to same
criticisms in the OP's link. Hence, I think the issues discussed in the
article don't singularly apply to REST.

------
tflinton
fairly idiotic.

~~~
dang
Please don't post unsubstantive comments. If something is wrong, explain how
so we can learn. Alternatively, if you don't have time to do that, please just
don't post anything.

------
joatmon-snoo
This reminds me a lot of Bret Victor's "The Future of Programming".

[https://www.youtube.com/watch?v=8pTEmbeENF4](https://www.youtube.com/watch?v=8pTEmbeENF4)

------
skrebbel
REST is successful for the same reason React Native is successful.

Before REST, there was SOAP, similar in spirit to the JSON-Pure solution
proposed by this author. SOAP's promise was a version of Java's "Write once,
run everywhere". In the case of SOAP, this meant that if you have a SOAP
client, you could consume data from any SOAP server with only the _domain
specific_ part different.

Like Java, SOAP over-promised. In practice, there was horrible incompatibility
between all the different SOAP providers and consumers; people lacked features
so they hacked it on to the protocol, only to discover later that the default
SOAP client in $THAT_OTHER_LANGUAGE didn't allow them to consume that hack as
easily as it was in the first language. And so on, and so forth.

REST, on the other side, hardly promises anything at all. In practice, most
people doing a REST API agree on _a rough idea_ of what URLs look like, and
yes let's do our best and embrace HTTP verbs and status codes. In a way, REST
is "learn once, use everywhere" \- not unlike React Native's motto.

This became wildly successful because the clients were all compatible from the
start (after all, HTTP was widespread already). Compared the SOAP and most RPC
setups, the clients are super underpowered; you need to do a bit of extra
work. The only way to know what URLs to compose is to read the API docs
(because HATEOAS is beautiful in theory only). The data is often JSON but
maybe not, and you're again going to have to pay attention to the docs.

In practice, though, it keeps the developer firmly in control. Most developers
using REST actually understand the entire protocol. They know enough HTTP to
be dangerous, they can look at what goes over the line and _it makes sense_.
The moment you add more features to the protocol, you just make it more
complicated and obtuse.

I'm not convinced that's a way forward, not without serious (GraphQL-level)
benefits.

