Skip navigation

Tag Archives: program design

Alright, so I received a pretty loaded technical topic from my good friend Matthew.  Mind you I asked for a technical topic to write about, and he did provide one but the question was:

What is an API and why/when would you use one?

Now seeing as how I already stated that is a loaded question, it deserves a bit of programming fundamentals.  I promise to keep this high level, but with enough detail that a novice programmer could glean a bit of workable information from it.

First I want to explain some basic program flow and design (paradigms).  I’m going to provide some very basic examples of procedural programming and object oriented programming using php (high level).  Lets begin with a very basic example of procedural code.

Put simply procedural programming is just building things to run in a sequence but dividing it up into functions or subroutines.  I’ve demonstrated examples of this in previous posts, but here’s a simple example:

	echo '<br />';

function example($arg)
	echo "This is a very simple example of $arg";

function endthis($arg)
	echo "This is the end of our $arg";

Ok, so what do we have here?

We have a prescribed run order, with a fixed goal in mind.  We are calling the function example with the argument string “functions”, echoing a break, then calling the function endthis with the string argument “example”. 

Simple enough, now why is this important?

Well it’s important to see the way I am passing arguments INTO the function in order for it to produce an output.

Now in more complex applications the best thing to do is to break apart your code and build it into objects (a collection of functions and variables) that perform like tasks and tie them together.  This is object oriented programming.

Lets just take a quick look at a sample object and how it works (stick with me, this is will become relevant to APIs I promise):

	$object = New SaySomething;
$object->set_words("jimmy crack corn and I don't care");

echo $object->get_words();

class SaySomething {
	var $words;
		function set_words($new_name) {
			$this->words = $new_name;
		function get_words() {
			return $this->words;

Ok, we instantiated the object we created, passed a string to it, then retrieved the sting.

Think of it like this, we have a program, we are loading it.  Once we have that program loaded we can begin to tell it what to do.  You can have as many instances of this object or other objects as your memory can handle. 

This paradigm affords us a massive amount of flexibility by giving us a standalone object for completing multiple like tasks.  It’s also easily extensible, allowing us to create child objects that inherit the functionality of their parent without having to modify the parent.  That will allow us over time to build a framework so to speak that we could use to quickly develop new applications on.

So, what does this all have to do with an API?

Looking at how the OOP paradigm communicates with each individual part, instantiating and then passing and receiving content.  An API isn’t much different than that.  The API simply exposes an application for communication.  It allows for interoperability from one application to another by passing messages to each other.

An example of common social networking APIs allow you to call for user information, as well as passing user information back.  Let’s use Twitter for an example. 

I want to post something to twitter, but from a custom application I’ve made.  I need a way to pass that information from my application to twitter.  The API is the interface point to allow that communication.  In a sense, twitter becomes my applications twitter object by virtue of calling and using the API (there are some stark differences, but generally this is a true statement).

The difference is, using the API doesn’t require intimate knowledge of what is going on behind the scenes.  I won’t be modifying anything within the application.  I’m simply sending and receiving information through the API.  The same is true for building an API, less is often more.  As you can imagine exposing your applications to external input and output can be a dangerous game; but that’s a much larger subject. 

The general take a way here is that although the application may consist of multiple functions and/or objects the API simply allows you to interlink one or more applications via messages.

A friend of mine Tom Miller put it rather well in a conversation we had over the subject.  “An API is a lot like a remote control”

I want the TV to change channels, I pick up the remote, press the channel up button, and the channel changes.  The remote IS the API.  My hand is the program communicating to it, and the TV is the program receiving the signal.  At no point do I need to understand how the remote works, or how the TV changed it’s channel. 

Ok, so when/why would I use an API?

That’s generally a design thing, but in most cases when you are building a platform or an application you want to improve it’s usability and not limit it.  Extensibility is the name of the game, so it makes sense to make something that would allow users to integrate other things with your application.

It’s good design because it achieves two major things towards (what I would consider) application design success.

1) It opens your platform up to the imagination of it’s user which can produce some really neat things.

2) It creates an operating environment for users with applications that depend on your platform which increases usage.

Hopefully this hasn’t left you completely confused, but like I said, it was a loaded question.