REST Is the New Soap(medium.com)
medium.com
REST Is the New Soap
https://medium.com/free-code-camp/rest-is-the-new-soap-97ff6c09896d
17 comments
I prefer to eat my own dogfood. That usually solves the problem. I design the API with two strictures: First: Any API I can use, my customers can also use. Second: Everything I design must use the API. No backend magic. No black boxes.
The rest (no pun intended) is just permissions.
The rest (no pun intended) is just permissions.
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.
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.
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:
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();
The autogeneration stuff works if you're talking Java to Java (or maybe C#) but for everything else it is a huge pain that's simply not worth it.
I agree with the article in principle but REST is an easier problem to handle especially with multiple languages
I agree with the article in principle but REST is an easier problem to handle especially with multiple languages
This is where documenting the API using OpenAPI / Swagger comes in handy. Then you can use code generation tools.
Why is OpenAPI not used more by those exposing public facing APIs?
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
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
Thank you!
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
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
[deleted]
Discussed at the time: https://news.ycombinator.com/item?id=15937448
His follow-up article https://medium.com/free-code-camp/follow-up-to-rest-is-the-n... 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.
His follow-up article https://medium.com/free-code-camp/follow-up-to-rest-is-the-n... 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.
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.
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.
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/05/08/hatoeas-is-for-humans.h...
https://intercoolerjs.org/2016/01/18/rescuing-rest.html
https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...
[deleted]
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.
Because you need HTTP to write web applications?
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.