Tim On Computer Science

2018 resolution: Say RIP to REST – aka “the year of RIP REST”

The specific resolution – only use “REST” casually, as a synonym for “client-server”

REST has had a pretty good run. The PhD dissertation was published in 2000. It did an awesome job describing the architecture of the web. Then some one, and then many ones, decided “the web” was a synonym for “enterprise network API”. That was a sad day, and the troubles began. Now, over a decade later, there is finally growing realization that “REST” is a terrible architecture for anything except web pages and maybe some key-value NoSQL APIs.

Section 5.1.5 “Uniform Interface” is one major failing.
Restricting a network architecture to the CRUD verbs is the opposite of “good network architecture”. This “Key-Value” design has been tried many times in the past. And rejected in almost every case. One domain where it stuck was “the web”. Another major failing in REST (although it is not in the dissertation) is the insistence on using HTTP response status codes at the REST level. This “mixing of levels” is another known anti-pattern (can you imagine writing your REST API using EBADF, EACCESS, EINVAL, etc.? Of course not, because the people who created HTTP understood protocol levels. But REST was attached at the hip to HTTP “for simplicity”).

It will be better days from now on – no more creating deficient network APIs in the name of REST. No more useless debates on versioning or HATEOS, or trying to “fix” REST. No more explaining “REST stands for REST Ein’t Soap, Tada!”. (Because that was all REST really was as a network API framework – REST was not SOAP.)

For those interested in what will replace REST, take a look at one possibility in GraphQL http://graphql.org/ GraphQL might not be the winner. But the winner will look a lot like it.

It has been fun developing AngularJS applications. It was the first complete framework that was both a higher level of abstraction than jQuery and easy enough (not “easy”, per se) to learn and use. You can even play with my Tic-Tac-Toe AngularJS applcation.

Then, around September, 2014, Angular 2.0 was announced, and 2.0.0 was released September, 2016. After 20 minutes of using Angular 2.0, it became clear that “drastically different” might have been an understatement.

It made me sad. Sad like when the Java people lent their name to JavaScript. A lot of confusion resulted, and Java took a hit that took a decade to recover.

“Angular” isn’t going to recover.

AngularJS was awesome, but Angular 2 was a classic case of “second system syndrome“. Angular 2 froze people out of AngularJS, but totally lost ground to the other libraries and frameworks. Angular 4 is out as of March, 2017, and the biggest thing they are bragging about is “Semantic Versioning“. They don’t seem to have much else to brag about, so why not? Oh yeah, ngIf now has an “else”. Yeah, that’s what is what is keeping Angular 2/4 down…

If there is ever a greenfield project in my future, it will use React with Redux and webpack.

Another likely alternative is Vue.js

[If the tone of this post seems weird, it is because this is a “record my current understanding and prediction” more than anything else.]

A seriously messed up post on Angular and React: here. It has the opposite prediction – that “Angular” is going to be great. Another messed up post is here. This post confuses AngularJS with Angular 2 (like, “Angular 2, created in 2010”)

Aurelia is another viable competitor in this field.

This is a very lively topic.

The starting point for these questions must be: in our world (enterprise grade computer science), what isn’t versioned? The answer to that is: everything is versioned.

Therefore, the actual question splits into two parts:
1) What makes REST and micro-services so special that they don’t get versioned? The answer here is easy – nothing. They must be versioned, just like everything else.

One post (here) tries to convince others of “versioning only as a last resort”. This book tries to convince others that “just monitoring the logs” is a sufficient solution to the problem. This is all amateur-hour stuff. Just ignore them.

Now that we know it must be versioned, the actual question arises:
2) How should the versioning be implemented in REST and microservices?

The choices seem to be:
1) URL: (e.g. http://yourapp/v1.2.3/person…)
2) URL parameter: (e.g. http://yourapp/person?Version=1.2.3)
3) Header – custom (e.g. “X-Api-Version: v1.2.3”)
4) Header – Accept (e.g. “Accept: application/yourapp.v1.2.3”)
5) Payload (e.g. inside the JSON { “version” : “v1.2.3”, “name” : “joe”, … } )
6) Hostname: (e.g. http://v1.yourapp/person)

People argue against #1 with strange arguments like a URL “represents a person” or “the idea of a person”. It is strange because “person” is not, and can not, be a universally workable concept. (Quick test if you are not convinced – write client side code that receives person JSON data, and computes the total of that person’s age and height. It can’t be done, for multiple reasons: you don’t know the keys and you don’t know the units. What if “age” is actually “bornAt” as milliseconds since the epoch?) The genius Roy T. Fielding simply got it wrong for the enterprise – a resource is a universal construct only in a university classroom. And, “Controls have to be learned on the fly” may eventually work once machines take over, but for now, even “age plus height” can’t be learned dynamically.

So – there just isn’t A concept of a person. There must be some implementation behind it, and that implementation needs to be versioned. Because in the enterprise world, something always changes.

The argument against #3 and #4 is a variation of the above: the URL “http://yourapp/api/person” makes it look like “person” is universal. But it is not universal. So the URL is a lie. It must be versioned.

The argument against #5 is the “surprise!” factor. Your client application had link to a person, but the data came back 3 versions in the future, and your client application has no mechanism available to “correct” the request, unless #1-#4 is provided. It’s the “box of chocolates” style programming – you never know what you’re going to get.

Since #6 is basically #1 with the “v1” moved to the left so much that it ends up in the DNS of the hostname, is shares the advantages. However, it proposes an uncomfortable use of DNS. And it ties the concept to a particular hostname (or pattern of hostnames, like “v2.stage.app.com”, “v1.prod.app.com”, etc.) In the end, it seems like a personal preference that a REST server should respond to requests without needing to know its DNS entry. (Or worse, creating option #4a: “Look for a version in the ‘Host:’ header of the request”).

One clever variation is just: do more than one! It seems like extra work, and you have to worry about conflicts (like 3 different versions in the same request). But, it does ensure that everybody yells at you equally 🙂

There are plenty of enterprise-grade APIs that use #1. They do differ on /v1/ versus /v1.0.0/, with the majority using the simpler /v1/.
* Dropbox – #1 (“/2/”), and is too embarrassed to document it
* Amazon – #2 (“/foo?Version=2012/01/02”)
* Twitter – #1 (“/1.1/”), also too embarrassed to document it
* Best Buy Developer API – #1 (“/v1”), also too embarrassed to document it
* Facebook – #1 (“/v2.5/”) with #3 in return (“facebook-api-version:v2.0″)

More links on versioning:
[showhide more_text=”Show Links” less_text=”Hide Links”]
– The cost of versioning an API
– Contract Versioning, Compatibility and Composability
– State Machines, Contracts and Versioning
– REST Versioning
[/showhide]

Quote from the book:
[showhide type=”book” more_text=”Show Book Quote” less_text=”Hide Book Quote”]
“Avoid Versioning Microservices and Endpoints”
“A microservice is not a library but an independent software application. Due to the fast-paced nature of microservice development, versioning microservices can easily become an organizational nightmare, with developers on client services pinning specific (outdated, un-maintained) versions of a microservice in their own code. Microservices should be treated as living, changing things, not static releases or libraries.”

My summary of that quote is “we are cowboy coders who can’t be bothered with puny details like versioning (or documenting, or up-time)”, i.e. amateur-hour again.
[/showhide]

Is Spring RestTemplate Thread Safe?

The only correct answer to this question is: No

A quick look at the source (the link is tied to a specific version so the line number is always correct) on line 230 shows the method “setMessageConverters” which mutates the field messageConverters without proper thread safe access or publishing.

There are multiple incorrect answers to this question found on the web:

• spring.io
• Stackoverflow.com
• codedump.io

All of these incorrect answers are actually answering the question: “Is there a way to use an instance of RestTemplate that is thread safe?” or just quoting other incorrect posts. (Especially disappointing is the blog post on spring.io. But, it was written in 2009, so maybe it was thread safe back then. Since at least 2012 (line 171) it has not been thread safe.) Or, they answer “Yes” then say “But don’t add a MessageConverter, because that is not thread safe”.

“Is there a way to use an instance of RestTemplate that is thread safe?” is a different question, and like all Java objects, the answer of course is: Yes.

If your code avoids the non-thread-safe methods, then you can claim thread safety.
If your code simply doesn’t call any methods on the instance, you can claim thread safety.
If your code only has one thread, you can claim thread safety.

But the actual code of RestTemplate.java shows that it is not thread safe.
And the typical use is to create a singleton instance that is used by multiple threads.
It is a “cross your fingers and hope nothing weird happens” kind of thread safe.

Which, of course, is not thread safe at all.