What is an API? By that I don't just mean what does it stand for. You can tell me that API stands for application programming interface. Yeah, okay. But what does that really mean?
Well, imagine for a moment you're a plumber. It's your first day on staff at a new location which might be an office building, an oil refinery, an apartment complex, miles of pipeline, or a massive system that’s already in place, running and working. See Fig 6.3.1.
Fig 6.3.1: A system of pipes on the roof of an automobile manufacturing plant
You didn't make this, somebody else did. Do you think your first task would be to take a big wrench to some random part of the plumbing and start unscrewing it? No. That's a good way to get fired or covered in some consequences. But neither is your first task to have to chart, draw and learn every single bend and curve, start pulling out the dry wall so you can memorize every joint and piece of solder behind the walls. That would be a pointless waste of your time.
The system is running, it works. There are parts of it that would work for decades without anybody's attention. What you do need to do is figure out how your supposed to interact with it. At what point is there some intentional place where you affect this? With plumbing it might be a shut-off valve or pressure gauge, with electrical work, a fuse box or a control panel, what we might call some kind of interface, a specific way to interact with the system.
It's the same in programming. It’s true the term interface happens a few times in software development. If a program has a user interface (not all of them do), that's what’s intentionally provided so that I as a human being can interact with the program. If a program has an API, an application programming interface, (again, not all of them do), that is what is provided so I can write code to interact with this program. Fig 6.3.2.
Fig 6.3.2: How API works
The thing is I don't want to have to learn exactly how that other program or system works. I don't want to read it source code. That would be the equivalent of pulling out all the dry wall and having to learn every bend and curve of the plumbing. I just want to know the smallest specific way that I am supposed to interact with it when I write my code.
Here’s an example. Supposing I'm writing a program and I need to be able to compress an image, but I don't know how. So, I do some searching and I find that there's a compression library where I can import news. That sounds good. But compression is difficult. So, any compression library I find is probably actually made of thousands and thousands of lines of code. Internally, it could be hundreds of methods and functions, dozens of different classes, but I don't care.
I only want to know how I'm supposed to write code to interact with this, that is, I only want to know what its API is. So, I look for some documentation. See Fig 6.3.3.
Fig 6.3.3: Sample API pseudocode
Perhaps, I'd find I'm supposed to first instantiate a new object
var myCompressor = new Compressor ()
I then tell it the name of my file
myCompressor.setInput(myImageFile
Then I read that I need to set the output file
myCompressor.setOutputName(“output.zip”)
And then I read I can change the compression type, but if I don't, that the default algorithm is fine for most things. Finally, I read, I'm supposed to call the zip method to go ahead and compress it.
myCompressor.zip()
Then I read a little further and find that this returns a status. So I suppose about a check to see if this worked
int result = myCompressor.zip()
if result 0 {
//something went wrong…
My hope is that I don't need my TODO anymore. So, I remove this line:
//TODO: compress image? how?
I get the functionality that I need without having to get any deeper into the details. Now as ever, this is of course pseudocode. There are compression libraries that are kind of like this, but what matters is the idea of the API, of how involved I need to get with this code. It's that process of finding out how are you supposed to write code to interact with another system, whether that's a library or a framework or something like a website.
Companies like Microsoft, Facebook and Google make multiple APIs available so you can write programs that interact with them, whether that's posting to a Facebook timeline or using Google maps. See Fig 6.3.4.
Fig 6.3.4: A Microsoft’s API
What you hope for is that the API is well documented, it's up to date and has some sample code. Sometimes you'll find ones that are a bit more primitive, and you have to use a bit of trial and error. But the hope is that by doing this, we once again save ourselves from having to reinvent the wheel as ever. You can expect different options depending on which programming language you've chosen to use, so it's about time we finally talked about that choice.