Tuesday, April 10, 2012

Why REST? Or "Simple vs. Easy"

This is a post that I want to write for years and cannot find the correct words. I'm fully aware that hundreds of blog posts have already fully covered this subject and still I want to write my opinion in my blog. It is my blog after all, right?

So "Why REST?"
But first, I'd like to say two words. One is "simple" and the second one is "easy". Although these words sound like synonyms, actually they are not. Some simple things can be not easy. And some easy things can be not simple.
For example: breathing is easy for most people, you don't need to think about it. But is it simple? Can you make someone breathe, if he doesn't?
On contrary cleaning an apartment is simple. But is it easy? Not for me at least...

The key point here is that simple things just work. They may not be easy to achieve, but once you do it, they work. Once you clean an apartment, you have a clean apartment. For a while at least.
But when something is not simple, its quite problematic even to understand how it should work. Sometimes it's easy to start (breathe for example), but what happen if something goes wrong (stop breathe for example)?

And now back to REST.
REST is simple. Not easy, but simple. Correct RESTful APIs are very clear, very simple to understand. They may not be easy to implement, but once implemented they work. It's quite easy to troubleshoot the RESTful APIs, you can do with with a simple HTTP Proxy (e.g. Fiddler). It ensures quite a decoupling between server and client.
Yes it takes time to develop a RESTful API. Yes there is no much automation around and suddenly a developer needs to develop a layer that he got generated with SOAP.

And now to SOAP (and other APIs that are generated from wslds/custom xmls/whatever): this one is easy. Usually I can get some working API very fast. There are a lot of tools that help you. BUT, it is not simple: the tools generate a lot of code that you don't know and sometimes not very readable. The integrations become very complex (did you ever install ESB?) The versioning becomes a nightmare. And the standards don't work very well (did you ever tried to integrate Java to .NET using some complex types?)

So the bottom line is: REST is simple, but not easy. SOAP is easy at the beginning, but not simple.
Simple is good, specially if you continue keeping it simple.
And forget about easy. Nobody said that a software development should be easy.


Nick said...

Well, I've developed an auto-generated RESTFull API :-)

Tarlog said...

Hi Nick,
My point was that REST in not a standard therefore it lacks the tools the exist for SOAP to generate client/server sides for multiple languages, technologies and platforms. Of course you can create some kind of standard for your project/organization and generate API out of it. But the main question: when you expose your API to the clients. Can you use the autogeneration tools? Or do you provide such tools for multiple technologies?

Alexander Stern said...

I think Jersey some JSON ORM tools like Jettison and JAX-RS are wonderful starting point technologies for creating and consuming RESTful API in Java.
Of course, similar tools probably exist for .NET and other languages.
Plus if we make sure to at least maintain XSD schemas for the objects being pass as well as consistent URI structure, the integration becomes much easier and doable.

Tarlog said...

I kinda got lost in your comment. Jersey is a reference implementation for JAX-RS.

Talking about JSON ORM tools, personally I prefer Jackson. It can work with POJO without writing any Jackson related code or putting annotations.

XSD is a different story. May be I'll write a separate post how do I think it should work. In general, I think that XSD is an overkill, even for XML and surely for JSON. XSD has many type definition some of which has no parallel in JAVA. JSON has no type definitions at all. If you are looking for a standard, DTD may be better in this case.
But I even don't think that you must stick to a standard, publish your schemas in any readable format, even as a wiki page. So your clients will need to do some job to create their ORM level. So what? It's one time job anyway.

Tarlog said...

Btw, I wrote some more posts about my view of a RESTful APIs, see http://tarlogonjava.blogspot.com/search/label/rest-design

Alexander Stern said...

Thanks for the clarification about Jertsey - didn't know that :)

About XSD/DTD - the point I wanna make is that having XSD allows simple creation of Object Model on client side and so easy usage of server RESTful API.

I believe, this is the main reason developers prefer SOAP when accessing web services - the ease of implementation of client side.

So having XSD, autogenerating Object Model and then accessing it seamlessly with JSON-JACKSON is or more generally - JAX-RS is a good way to go.

JAX-RS allows annotation level selection of underlying format XML/JSON so it's good to have as an option!

Tarlog said...

I fully understand your point. I myself thought this way ~3-4 years ago, when I first needed to create RESTful APIs, so starting from xml was a natural choice. After all we all have been used to SOAP.

But now I don't think XML is a must.
I don't think that having a strict schema is a must. Actually I think that a strict schema makes more problems than benefits.
(I tried to summarize it here: http://tarlogonjava.blogspot.com/2012/04/rest-best-practices-use-json.html)
And I don't think that making client's life a bit easier by providing an XSD is a must. If a client must connect to you, it will regardless if you provide an XSD or a document describing your API.
And if your goal is to make client's life easy, you need not provide an XSD, but a library that connects to your APIs.
But nothing will make the client more frustrated, if you provide an XSD and the generation will not work as expected. After all you don't know which technology the client uses and you have not tested your XSD with it. And now instead of creating a set of simple classes, a client is busy understanding why the generation didn't work as expected. And this is exactly what everyone hated about SOAP.

Anonymous said...


Btw what tools do you use to generate your REST APIs?

Currently I'm looking for such tools and there are so many...