Blogs

Couple things happened today (Friday, of all days):

1. My old blog hosting company sent a "we are shutting down" notice. Out of curiosity I clicked through and quickly found myself reading 5-year old posts. One of them was ranting about code maintenance.
2. A friend tweeted a link to a blog post by Rohan Singh: Isn't All Coding About Being Too Clever? where he's also talking about maintainable code (with a different perspective).

This got me thinking...

In majority of software engineering literature, "maintainability" of code is hailed as sacred. It's easy to relate to the sentiment: no code gets written once and then forgotten. When you ship code, you give it birth, but the actual life of that code is only just starting. You want to make sure your code spends its life well -- goes to college, marries the right person, and makes the "parents" proud when other people have to deal with it (that's the maintenance part).

Except, much like with kids, your plans for your code almost never work out as initially intended. If you are smart enough you accept them just the way they turn out to be (at least - code, if not kids) , without trying to be a control freak. And that's where this obsession with "maintenance" can become a problem.

APC 3.1.9 has a nasty bug, causing a frustrating error: "PHP Fatal error: Unknown: apc_fcntl_unlock failed: in Unknown on line 0" to appear when installed with PECL on Mac OS-X (and reportedly on a variety of Linux platforms).

There's an easy fix.

Elastic Search is a fantastic, clustered search server built on top of Apache Lucene search engine. It's very easy to install and configure.

However, on some servers, if you follow instructions (which is basically: download, unpack, run: bin/elasticsearch) you may get a weird permission error:

$ ./elasticsearch 
exec: 179: : Permission denied

even though there are no apparent permission problems and even if you run the script with sudo (which you should not have to).

The solution is extremely simple: if this happens, the real issue is that you do not have JDK 6. I know, that's not what the error complains about, but that's typically the root problem. Install JDK6 (e.g. with: "sudo apt-get install openjdk-6-jdk" on Debian) and the problem will go away.

It's not always easy, in PHP, to figure-out which PHP ini files are actually parsed and loaded. CLI may use diff set than web, and if you are using NginX with FPM, there may be yet another set.

Following extremely simple piece of code can greatly help in clearing-up the confusion:

print_r( php_ini_loaded_file() );
print_r("Scanned: ");
print_r( php_ini_scanned_files() );
exit();

I like Espresso from MacRabbit for server-side scripting a lot. The latest version (2.0) has merged a wonderful code editor with the best-of-the-class CSS editor, giving one awesome, unified experience. And, of course, you can edit your files directly over an SSH connection (the latter, alas, is not as straightforward as it is in Panic's Coda, but, well, we love both of them for different reasons).

Nothing in this life is perfect, however. One glaring shortcoming of Espresso is: no UI for assigning a syntax highlighter to custom file extensions. Espresso recognizes most common file extensions, but if you do something slightly different, e.g.: use .tpl files in Drupal (which are PHP files) or use Handlebars templates in Javascript (which are basically HTML), you won't get default syntax highlighting because Espresso does not know what type of files these are.

Let's see how we can teach Espresso custom file types. I will do this for .handlebars files, which are template files I use for my Javascript coding.

1. Right-click on Espresso.app in Finder and select: "show package contents".
2. Go to folder: Contents > SharedSupport > Sugars
3. Right-clic on "XML-and-HTML.sugar" and select: "show package contents".
4. Open Languages.xml for editing (with vi, Textmate or whatever your favorite text editor is)
5. Scroll down to detectors section which should read something like:
   

   <detectors>
     <extension>html</extension>
     <extension>htm</extension>
     ...
   </detectors>

6. Add more extensions to the section, e.g. for handlebars, I added:
   

   <extension>handlebars</extension>

With the increasing popularity of server-side Javascript, you may want to have Javascript everywhere. You can use Javascript outside of a browser, on any platform. There are many choices: you can install Mozilla SpiderMonkey, Google V8 or Mozilla Rhino. If you are like me and use Mac OS-X as your development machine, however, you have hit a jackpot: OS-X Leopard and later come with Javascript CLI pre-installed. The CLI uses JavascriptCore by Apple, the same engine used in the Safari browser, and many other places all over OS-X.

This is how you can enable JSC:

$ sudo ln -s /System/Library/Frameworks/JavaScriptCore.framework/Versions/Current/Resources/jsc /bin/jsc

Once you do that, you can run the jsc interactive shell or write javascript shell executables by putting:

#!/bin/jsc

at the top of a shell script. JSC Wiki lists some extra commands you can use in your CLI scripts.

Alternative JS CLIs

If you install Homebrew, "the missing package-manager for OS X" (generally a great idea for a developer), installing Google v8 or Mozzila Spidermonkey or Rhino becomes trivially easy:

$ brew install v8
$ brew install spidermonkey
$ brew install rhino

For Rhino, you need to make sure you have Java installed on your Mac. If you do that, JS executables will correspondingly be located in:

/usr/local/Cellar/v8/HEAD/bin/v8
/usr/local/Cellar/spidermonkey/1.8.5/bin/js
/usr/local/Cellar/rhino/1.7R3/bin/rhino

Typically, brew will also create convenience symlinks:

/usr/local/bin/v8
/usr/local/bin/js
/usr/local/bin/rhino

It's a pretty common need to format an array as a proper comma-delimited string for use in SQL's "WHERE ... IN" clause. Following is a simple solution that demonstrates how closures in PHP 5.3+ make writing such code pretty elegant. A unit-test is included to demonstrate several edge cases:

Following is a step-by-step guide to installing the latest CouchDB release on Debian Squeeze from sources.

Installing Prerequisites

Install prerequisites and latest Erlang

RabbitMQ can install Erlang for you, but it does not install latest Erlang/OTP, which can cause problems when you try to install Admin UI, so it's the best to just compile latest Erlang/OTP

$ sudo apt-get update
$ sudo apt-get install build-essential
$ sudo apt-get install libssl-dev zlib1g-dev lsb-base 
$ sudo apt-get install ncurses-dev libncurses-dev
$ sudo apt-get install libcurl4-dev libcurl4-openssl-dev 
$ cd /usr/local/src/
$ sudo wget http://www.erlang.org/download/otp_src_R14B03.tar.gz
$ sudo tar xzvf otp_src_R14B03.tar.gz 
$ cd otp_src_R14B03/
$ sudo ./configure 
$ sudo make && sudo make install

Erlang compilation will complain about jinterface, odbc, wx and xsltproc and fop. We do not need any of that for our purposes, so please feel free to ignore.

Install RabbitMQ from Repo

Add the following line to your /etc/apt/sources.list:
deb http://www.rabbitmq.com/debian/ testing main

"REST vs. SOAP" has been an ongoing battle for quite a while, in the tech industry. There is a seemingly upwards trend of the number of open RESTful APIs emerging vs. the SOAP ones. It's probably safe to conclude that, at least among open APIs, REST is winning.

The problem, however is the ambiguity of the answer to the basic question: what is REST?

RESTful API Design

Representational State Transfer (REST) is an architectural style, for distributed hypermedia systems. It was initially defined in 2000 by Roy Fielding in his doctoral dissertation. REST is based on the concept of transfer of representations of resources. A resource is any application entity that can be uniquely addressed with a Uniform Resource Locator (URL). A representation of a resource is a document that captures current or intended state of a resource.

Since REST is an architectural style not: a well-defined specification, it leaves a lot for interpretation. However, with the increased proliferation of the RESTful style in popular web APIs, some common traits have emerged which are now recognized as best-practices in RESTful web API design. REST, in theory, is not limited to the web, but for the purposes of this blog post we assume to be discussing REST in the context of the world-wide web.

Basic Principles

• Proper RESTful APIs extensively utilize HTTP Protocol. Usage of HTTP methods for CRUD, standard HTTP response codes, common HTTP headers and Mime Types is a common practice.
• URLs in RESTful APIs are semantic, resource-centric and have a general structure which looks something like the following:
  

  http://api.example.com/{ver}/{lang}/{resource_type}/{resource_id}.{output_format}?{filters and api_key as arguments}

  where: