I get asked a lot lately, "What is an API?"
You'd think this would be something you could Google and be done with, but the problem is, apparently no one has told the folks writing all the API articles that the folks reading the articles don't know what API's actually are!
Well, if that's you, you're in luck! This article assumes zero IT knowledge. I will take you through what an API is in such a way that almost anyone can understand it.
So are you ready to join me on this journey?
Let's do this!
What is an API?
Before we unpack the nuances of API's and how they work, let's first dive into what the letters mean. So an API stands for an Application Programming Interface. I find that when explaining API's it's best to explain what each of the words means first.
Application
An application is simply a piece of software that performs a purpose. You are using an application to read this article right now. Well, inside an application there is this mysterious thing called code. Code quite simple is just instructions for your computer, phone, or whatever device you are using. These instructions tell your device what to do.
Programming
Programming is another word for code. But the big difference is that programming is organized. I could type out a bunch of "code" but it would be meaningless if I didn't organize it. Programming is the act of organizing code.
So when I say programming what I am really saying is organized sets of functionality (more on this later).
Interface
Have you ever plugged a USB cable into your computer or looked up something on Google? Then you my friend have used an interface. This is the part that trips a lot of people up but it shouldn't. Do you remember back in the day when you actually had to look up books in the library using a catalog?
Do you remember back in the day when you actually had to look up books in the library using a catalog?
You would go to these long draws and you would search for a structured set of numbers that indicated your book. Well, that's what an interface is doing to your application.
When you use an interface to your application you are essentially looking up certain pieces of programmed code that you can then interact with.
So what does this look like?
Well if you went to Google right now. You could use their search API to search for something.
Let's say I wanted to look up Apples. What would that look like?
As you can see, it sure looks like I am using google search. And the funny thing is I am. My application (in this case Google Chrome Web Browser) is accessing the search function of the Google Search API. You can see that I have received 2 billion results for the word Apple.
Try it out type https://www.google.com/#q={enter your search term here without the brackets}.
By the way, the thing I just posted above that's called an API string and when I type it in my browser and hit submit that's called an API Call.
Congratulations you just used your first API.
So what's the big deal?
So you often hear about this BAS and that system have open API's. Folks tend to throw these terms around like crazy, most of the time without understanding what they mean.
Let's look at an API I use quite commonly.
Here is an example of an API string that is calling on the WeatherUnderground API to get weather data for London.
http://api.wunderground.com/api/0def10027afaebb7/conditions/q/canada/Toronto.json
Don't try to use the link above it won't work.
The reason why it won't work is that the "key" (highlighted portion of the link) is not a working key. A key lets the API know that you have permission to make calls (remember a call is when we request data from an API)
So what would it look like when I submit this call with a good key?
I would get something like this back from the API.
So before you freak out, realize that all you are seeing is simply a list of returned values from the API. You use API's every day. When you make deposits to your bank when you log in to your BAS and change temperatures.
The big difference is that the API is covered up by something called the presentation layer (this is a very fancy way of saying user interface).
Now an API is not just for getting data, although that is a very common use for it. Remember when I mentioned that programming piece?
Well now that we are comfortable with API's, in general, I'm going to talk about functions....
Functions are simply predefined commands that the "program" inside the application can perform.
Want to turn on the lights simply call the commandLights function. Want to schedule a room, simply call the scheduleRoom function.
Now here is the part that confuses BAS folks... How do you get from the raw API functions I showed you above and turn them into something your BAS can work with.
You do this through integration. When you are truly integrating you are connecting two different systems together. In order for a weather station API to connect to my BAS, I have to consume (meaning connect to and read/write data to and from) the API.
There are two ways of doing this but I am going to only cover the most popular method.
Method 1: Use data adapters
Now for those of you who are programmers you're going to cringe because I'm being purposely vague (I'm not calling out design patterns or endpoints, etc). But for the rest of you, this will make perfect sense.
What I am doing is taking the API and I am writing a computer program. This computer program will run on my BAS server and it will take data from the weather station API and send it to the BAS API. This is often known as a data adapter.
How do I know what to do?
This is a common question. How do you know what to do? What calls to make? What data to expect back?
You know this through an SDK. An SDK is a software development kit.
A good SDK will define all of the calls you can make and will define the data you are expecting to get back. It will also provide examples of how to write the calls to the API.
Conclusion
So there you have it. That's what an API is. I know I left some of the more nitty-gritty technical details out but this article should give you a working knowledge of what an API is and how it works. If you really want to dive deep on API's. then I encourage you to pick up this book
If you find yourself struggling with these kinds of IT concepts then I really encourage you to check out my new IT Video Training course. This course is unlike any other course in that it is written specifically for BAS professionals and assumes no prior knowledge.
Depending on when you click this link the course may be closed so I encourage you to join the waitlist so that you will be notified when the course opens up.
