For Developers

Reverb Developer Blog

Dissecting Our Wordnik Developer Site

by Tony Tam  |  Posted March 14, 2013

wordnikapi_logo

To those familiar with the Wordnik developer site, it looks unchanged. There’s a section for code libraries to connect to our API, examples of applications using the API, and of course the Swagger Sandbox. Functional, simple, and easy to navigate.

But just the other day, the site was totally rewritten in HTML, CSS, and Scala. And the lines of code dropped to 1/10th what they were before. What’s the deal? And what makes it so much snappier now?

We’ve updated the site to follow an emerging web architecture called a Single Page Application, or SPA, which allows the browser to serve all display and rendering logic. The UI, via JavaScript, has plenty of power to decide what to show the user, and keep state as needed. The HTML is more semantic – meaning the layout follows the content more than the display logic (no more <table> overuse!) and CSS can respond to media queries, meaning small-form devices or different screen layouts can switch rendering templates without reprocessing data on the server.

As an added benefit, the consumer (your ultimate judge) gets a snappier, lighter weight experience which can even work offline. Sounds great, right? So how is this done?

If you view source on the developer site, you’ll see that it’s pretty much empty. Aside from some JavaScript and CSS files, there are just a few <div> elements which serve as basic containers for the application: a header, a content section, and a footer.

site-source

As the page loads, the JavaScript will call the API server (powered by Scalatra) and load a chunk of data. You can see that happen in the chrome’s network panel. Once that data is received, it’s inserted into the DOM under the header div. Let’s look at that more.

xml-source

Note here, the response from the API server is HTML, not JSON. Why is that? Well, we’re keeping the client-side rendering as light-weight as possible. The server is extremely good at efficient generation of XML. The client, however, has to keep state of the DOM during manipulation (there are tricks to lessen this burden, of course), plus this header almost never changes.

So why bother put in the rendering logic on the client? All that’s required is a simple call to `load` the content into the DOM:

js-inject

Same goes for other sections. We’re simply removing and replacing entire DOM elements – big ones – with pre-computed, rendered HTML. No fancy JavaScript is required for this part of the site, and the entire client-side code including comments is only 142 lines before minification. There’s really not a whole lot to go wrong in that code.

The server is just as simple to write. Using Scalatra, we simply generate XML and send it over an HTTP get call.

A trait defining the header, in XML:
common

Mixing in the trait into a singleton object:
server-service

Finally, the GET method to support the request for the header HTML:
scalatra-api

Of course, backing the XML generation with a database call, fancy logic, etc. is trivial. As you might guess, the code to generate this site, both client and server, should be tiny. And it is – in fact, the server codebase to generate developer.wordnik.com was cut down to 1/5th the original size, while the templates, JavaScript, and CSS were cut to 1/20th the old implementation.

Now for a simple site like developer.wordnik.com, do you need to do fancy techniques like this? Of course not, but we’re developers, and what better place to show what we consider to be best practices than our developer site, right?

Filed under: api, scala | Permalink | 2 Comments

{ 2 trackbacks }

Reverberations: Wordnik Developer Site, language news, blogging news
03.15.13 at 10:29 am
Reverb News: Xconomy, Wordnik Developer site, WSJ and AWP words
03.25.13 at 10:46 am

{ 0 comments… add one now }

Leave a Comment

You can use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>