How often have you accomplished something really worthwhile all by yourself, in a complete vacuum? You did something good without any help or advice from anybody, no information, materials or services from any outside sources? Perhaps you have but most of the time when we accomplish something worthwhile it isn’t in a complete vacuum but rather with help, inspiration or information from outside sources.

Web applications are much the same: most web applications nowadays aren’t stand alone, siloed applications anymore but share information with other computer systems. Web applications can source news, weather, maps, feedback widgets and many more from other computer systems and similarly provide their own information to outside systems.

REST API is a bit of a buzzword nowadays in programming but essentially it’s an architectural style of programming to allow independent computer systems to communicate with each other. For many developers the nuts and bolts are actually easier to understand than the concept and this past week I found myself at the office explaining the concept of REST APIs using Peruvian history, culture, and my inlaws. Listen in!

Let’s say Bloomie got tired of mellow and decided to run some IKN content. And the Economist, Otto’s alma mater and a handful of his blogging buddies all wanted to run IKN content as well. Prior approval and a small nominal fee. Otto decides to make the following content available to other computer systems:

• Top three most visited IKN posts
• Chart of the day
• Friday OT

The programmer bloke sets up a new URL at api.incakolanews.com which is essentially the home page of the machine readable version of IKN. The output of this URL is not human-readable, it’s some machine-readable format like JSON. Asi:

All that jibberish just means that the machine readable home page of IKN has no content other than 3 links to the specific sections Otto makes available to client computer systems.

But you wanted to hear about my inlaws, and Peru, no?

Once upon a time there were big land owners in Peru, you can still see the abandoned mansions around the Peruvian countryside. Under the military government of Velasco in the late 1960s land owners were expropriated. Then followed a collapse of the agricultural economy and massive migration to the cities. Among the land owners who were expropriated were my wife’s family. They weren’t big land owners or wealthy by today’s standards but they were land owners nonetheless. Today divisions remain in Peru, not just between rich and poor but who you are, where you come from, the part of town you live in, often determines how you live more than your personal economy does.

Better if Mamacita Linda doesn’t hear about this but it’s possible every now and then I might have vented at the office about my inlaws, how supremely spoiled some of them are. Not in terms of material possessions but rather “I’ll be attended, any time all the time”. I know that sounds terribly harsh but maybe they were just a product of their environment. Maybe they still hold a grudge over the expropriations, on some level I could understand.

Back to the REST API. APIs are big money, not the kind of “can I write some sponsored content on your blog and pay you $0.35 for every 2 million clicks” kind of money. APIs provide your core content or functionality to other computer systems, so if your content or functionality has value, your API is worth a lot of money. The overriding concern then in programming an API is to make life easy on your client applications. The easier your API is to consume, the happier your clients will be.

If I had to write the fictional IKN API, the only code Bloomie and all of Otto’s other clients would need is this:

Five lines of code, give or take. Of course there’s a lot of work on the IKN side to make this possible but on the client side 5 lines of code should be all that’s needed to present the information to the end user and allow the end user to navigate through the content provided by the API.

The other day some of our developers were working on code for the next phase of the CoolCalc applications and a whole bunch of code was in the process of being written for client applications. I struggled to explain the REST API concept for a moment. You see where this is going.

“Think of the client applications like my wife’s aunt so-and-so!”

Not to generalize but it isn’t sarcasm or an exaggeration to say some children of expropriated Peruvian land owners don’t know how to cook a hard boiled egg. They don’t want to know how to cook a hard boiled egg. Obviously – in their mind – the hard boiled egg should be served for them. Once I’m done you can clean the table.

A REST API should be designed as if the client applications are those types of Peruvian inlaws. Our developers are from all types of backgrounds but every one of them understood 😉

Abandoned hacienda of expropriated Peruvian land owners, near Paruro.