
REST Is the New Soap - kiyanwang
https://medium.com/free-code-camp/rest-is-the-new-soap-97ff6c09896d
======
olau
I am personally of the opinion that anything but a handcrafted API is dumb.

The API is where you help your users while preparing for future. It's not
something to be left to mere coincidence.

HTTPS + JSON is relatively convenient for taking care of transporting the data
over the network in a platform-neutral manner. But you still need to do all
the design work.

Just like a great programming library. It's just harder because it's
distributed.

~~~
Juliate
This.

We don't need to have all interfaces consistent between each other (although
this integration might help), but we need them to be consistent with
themselves.

Offloading the integration work to a standard interface or library is good,
but don't expect to extract the best of the interaction with it only - because
the best is precisely at the margin, what is hard to standardize, at the
moment in time you are looking at it.

Although it is GOOD to have interfaces/contracts, industrialized things of
course.

But the majority of the proponents of these I've met in the industry are the
same people that do not care about or understand (for reasons - valid or not)
the lifecycle or the normative quality of what they're doing, with the
assumption of deferring it to something/one else.

And, with the comparison with SOAP... REST is a mess, yes. But it is
considerably less hard to understand and wrap around than SOAP. And it
introduced so many better practices and outcomes in the thinking and design
and exposure and usability of APIs.

~~~
aurbano
The problem is that we went backwards in many ways...

REST made it easier to define the API and to understand, but pretty much
impossible to autogenerate a client for example.

With a well made SOAP API you can autogenerate client code for it, that is
type safe and self-documented almost.

For example after using cxf to autogenerate Java for a given SOAP API I may be
able to then write in my app:

    
    
      SampleApiRecord record = new SampleApiRecord();
    
      try {
        record.authenticate(token);
      } catch (AuthenticationException e) {
        // auth failed
      }
      User user = record.getUserData();
    

This can still be painful to use, but at least REST could've built on top of
these concepts

~~~
yardstick
This is where documenting the API using OpenAPI / Swagger comes in handy. Then
you can use code generation tools.

~~~
toomuchtodo
Why is OpenAPI not used more by those exposing public facing APIs?

~~~
Juliate
I'd say because most of the time, 1) the product is designed iteratively, and
not API-first (where a clean spec of the API could be done) but most-
obvious/target-usage-first (where hand-made/refined queries are done); 2) and
then you patch things on top of it.

You may claim that there's a lack of architecture/thinking into this. There
is. Precisely because when you build something new, or something you don't
master, you go for it iteratively, instead of deep-thinking it.

And after that, when you have your v1, you can redesign it "properly" with a
contract, etc. as a v2.

And here again with the v2, you will be asked to build/integrate some other
new stuff. Or usage will evolve in a way you didn't project. So you will end
up patching either your API directly, or the contract first.

And reactively, again.

And no, architects won't be involved, because their time is supposed to be
best spent doing pre-sales, or proof-of-concepts, or suggestions for v(n+1),
rather than mingling with developers or production teams about operational
matters. /sad sarcasm

~~~
toomuchtodo
Thank you!

------
aurbano
So what is the alternative? I've used RPC, SOAP with autogenerated Java
methods via CXF, and tons of REST APIs that are just "random" JSON objects.

I agree with the author that REST is not as great as people seem to imply.
Yes, it's easy to setup and get started, but the main problem is the lack of
control. If I need a certain piece of data along with sub elements, and their
sub elements - and the API doesn't already expose this exact object (or a way
to request it, using custom query params for instance) - I'm left with the
only option of issuing query after query (N + 1 query problem mentioned in the
article)

GraphQL looks extremely promising in that sense, as finally the client decides
what they will consume, and I can't wait to use it at some point.

My issue with it though (which has been a show stopper so far) is that complex
authorisation for subsets of data and business rules around updates to the
data seem (very)hard to achieve, but I'd still like to see an architecture
that supports this easily.

I'd love to hear other's experiences with it, or other tools that solve the
problems outlined here!

Edit: Improve writing a bit

------
rauhl
Discussed at the time:
[https://news.ycombinator.com/item?id=15937448](https://news.ycombinator.com/item?id=15937448)

His follow-up article [https://medium.com/free-code-camp/follow-up-to-rest-is-
the-n...](https://medium.com/free-code-camp/follow-up-to-rest-is-the-new-soap-
the-origins-of-rest-21c59d243438) is not _quite_ as bombastic and somewhat
more mature, although IMHO it has errors too.

My own complain about REST is not about REST itself (because I think it’s
great) but about the fact that it has come to mean ‘anything with HTTP and
JSON.’ As the follow-up article notes, a really RESTful interface is going to
define its own MIME types. Now, they might be JSON (or something cleaner, like
S-expressions …), but they needn’t be. REST is about data and operations on
data and data about operations — it’s not about JSON.

------
joshstrange
I'll take REST over SOAP any day of the week. Every time I've dealt with SOAP
it's been magnitudes of times more confusing and frustrating than any REST
endpoint I've used.

That said this article is SPOT ON with the failings of REST. The bit on HTTP
error codes hit me hard. At my last company we used unused HTTP codes to
represent various server errors (we kept them in the correct ranges for
client/server errors). The only problem is at some point someone used 408
("408 Request Timeout") to indicate the server timed out (we should have used
"504 Gateway Timeout"). I'm sure someone typed something like
"HttpStatus.Timeout" and the IDE helpfully provided
"HttpStatus.REQUEST_TIMEOUT" and they said "well it's a request and it's
timing out so perfect". Unfortunately modern browsers see a 408 and think THEY
did something wrong (That they didn't send the request fast enough) and so it
RETRIES THE REQUEST!

> HTTP existed long before “RESTful webservices”, and the web ecosystem is
> filled with assumptions about the meaning of its error codes. Using them to
> transport application errors is like using milk bottles to dispose of toxic
> waste: inevitably, one day, there will be trouble.

So while we would be debugging a request the browser would get a 408 from our
server (because we had paused execution for longer than our http adaptor's
timeout for talking to backend, the browser would resubmit the same request,
and once we had resumed debugging we would get a second message dropped into
the system. We wrote this off for MONTHS as some debugging-related oddity. I
know I personally took 5-10 minutes on multiple occasions to track it down but
the Chrome network monitor DOES NOT show the retry which makes it even more
confusing.

Finally we were forced to find the issue and fix it... when it took down
production. We had an endpoint that started to hang a huge part of the system
(it was a bug where it couldn't handle the amount of data in prod) and when it
timed out the browser would just retry the request so every open web browser
pointed at our site because a DDOS client.

------
hikefast32
REST is largely pointless without HATEOAS, and json isn’t a hypertext
natively. It was a cargo-cult from the beginning.

[https://intercoolerjs.org/2016/01/18/rescuing-
rest.html](https://intercoolerjs.org/2016/01/18/rescuing-rest.html)

[https://intercoolerjs.org/2016/05/08/hatoeas-is-for-
humans.h...](https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html)

------
mkettn
I've never understood all this excitement about REST. If you need a special
service, just code a small shell program and register it at /etc/inetd.conf.
if you need security, pipe your text file thru OpenSSL/pgp or use ssh instead.

~~~
rhinoceraptor
Because you need HTTP to write web applications?

