Problems with RESTful APIs (2015)

> 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...

[2] https://docs.python.org/3/library/json.html?highlight=json#b...

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.

> 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

> 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.

> 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 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 ?

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.