Separate REST JSON API server and client?

Very well asked. +1. For sure, this is future useful reference for me. Also @Aaron and others added value to discussion. Like Ruby, this question is equally applicable to other programming environments.

I have used the first two options. First one for numerous applications and second one for my open source project Cowoop

Option 1

This one is no doubt the most popular one. But I find implementation are very much http-ish. Every API's initial code goes in dealing with request object. So API code is more than pure ruby/python/other language code.

Option 2

I always loved this.

This option also implies that HTML is not runtime generated on server. This is how option 2 is different from option 3. But are build as static html using a build script. When loaded on client side these HTML would call API server as JS API client.

• Separation of concerns is great advantage. And very much to your liking (and mine) backend experts implement backend APIs, test them easily like usual language code without worrying about framework/ http request code.

• This really is not as difficult as it sounds on frontend side. Do API calls and resulting data (mostly json) is available to your client side template or MVC.

• Less server side processing. It means you may go for commodity hardware/ less expensive server.

• Easier to test layers independently, easier to generate API docs.

It does have some downsides.

• Many developers find this over engineered and hard to understand. So chances are that architecture may get criticized.

• i18n/l10n is hard. Since HTML is essentially generated build time are static, one needs multiple builds per supported language (which isn't necessarily a bad thing). But even with that you may have corner cases around l10n/i18n and need to be careful.

Option 3

Backend coding in this case must be same as second option. Most points for option 2 are applicable here as well.

Web pages are rendered runtime using server side templates. This makes i18n/l10n much easier with more established/accepted techniques. May be one less http call for some essential context needed for page rendering like user, language, currency etc. So server side processing is increased with rendering but possibly compensated by less http calls to API server.

Now that pages are server rendered on server, frontend is now more tied with programming environment. This might not be even a consideration for many applications.

Twitter case

As I understand, Twitter might does their initial page rendering on server but for page updates it still has some API calls and client side templates to manipulate DOM. So in such case you have double templates to maintain which adds some overhead and complexity. Not everyone can afford this option, unlike Twitter.

Our project Stack

I happen to use Python. I use JsonRPC 2.0 instead of REST. I suggest REST, though I like idea of JsonRPC for various reasons. I use below libraries. Somebody considering option 2/3 might find it useful.

• API Server: Python A fast web micro framework - Flask
• Frontend server: Nginx
• Client side MVC: Knockout.js
• Other relevant tools/libs:
  • Jquery
  • Accounting.js for money currency
  • Webshim : Cross browser polyfill
  • director: Client side routing
  • sphc: HTML generation

My conclusion and recommendation

Option 3!.

All said, I have used option 2 successfully but now leaning towards option 3 for some simplicity. Generating static HTML pages with build script and serving them with one of ultra fast server that specialize in serving static pages is very tempting (Option 2).

At Boundless, we've gone deep with option #2 and rolled it out to thousands of students. Our server is a JSON REST API (Scala + MongoDB), and all of our client code is served straight out of CloudFront (ie: www.boundless.com is just an alias for CloudFront).

Pros:

• Cutting-edge/exciting
• A lot of bang for your buck: API gives you basis for your own web client, mobile clients, 3rd party access, etc.
• exceedingly fast site loading / page transitions

Cons:

• Not SEO friendly/ready without a lot more work.
• Requires top-notch web front-end folk who are ready to cope w/ the reality of a site experience that is 70% javascript and what that means.

I do think this is the future of all web-apps.

Some thoughts for the web front end folks (which is where all the new-ness/challenge is given this architecture):

• CoffeeScript. Much easier to produce high-quality code.
• Backbone. Great way to organize your logic, and active community.
• HAMLC. Haml + CoffeeScript templates => JS.
• SASS

We've built a harness for our front-end development called 'Spar' (Single Page App Rocketship) which is effectively the asset pipeline from Rails tuned for single page app development. We'll be open-sourcing within the next couple of weeks on our github page, along with a blog post explaining how to use it and overall architecture in greater detail.

UPDATE:

With respect to people's concerns with Backbone, I think they are over-rated. Backbone is far more an organizational principle than it is a deep framework. Twitter's site itself is a giant beast of Javascript covering every corner-case across millions of users & legacy browsers, while loading tweets real-time, garbage collect, display lots of multimedia, etc. Of all the 'pure' js sites I've seen, Twitter is the odd one out. There have been many impressively complicated apps delivered via JS that fare very well.

And your choice of architecture depends entirely on your goals. If you are looking for the fastest way to support multiple clients and have access to good front-end talent, investing in a standalone API is a great way to go.