(Click here to read the overview, Part 1 of What’s An API?.)

Author’s Note: This series is intended for a more general audience to understand broad concepts, not a how-to for developers. Although hopefully it is of use to developers to contemplate the nature of these terms too.

* * *

So we generally have an idea what APIs are now. Let me throw my definition at you all to refresh what we’ve learned: An API is an interface that software code can use to execute a command or retrieve a set of data..

In Part 2 we discussed APIs that are a native part of an operating system. Those are pretty foundational commands and functions; they are so integral to code that it’s hard to think of them as APIs instead of just the basics of coding in any environment or OS.

Where it gets more interesting are APIs that not only run other apps (like Outlook, Google Chrome, iTunes, etc.) but those APIs are your way in to control and access elements of those programs.

When Do You Use These

The most obvious cases are when you have to interact with a program. If you need to interact with enterprise software like SAP, Salesforce, Maximo, etc. then their APIs are the way your code will read, write and manipulate data. Do you need to sort through an Excel file to display data? Excel APIs are how you’re gonna do it.

Other times for application APIs are when you know that your code has to do the behavior of another app. Do you want your code to let somebody subscribe to a podcast? In that case you’d want to use iTunes APIs and you could theoretically have your own branded form with an element inside that silently pulls off some iTunes functions in the background. Do you want to draft an email for the user to send? You can create an email with the recipients, subject, body, attachments all there -- whether you send it without the user’s permission or whether you even show Outlook or keep it hidden, that’s up to you.

Or maybe you want to accomplish something in your code, but you’d love a shortcut to pull in an API and just make one call to the API to pull something off. Let’s say you have to read something from an Oracle database of yours. You could use Windows APIs’ data connection methods (giving it the proper parameters for an Oracle database). You could use Oracle APIs (recommended). Or possibly you read about a great API on the internet that has nifty Oracle functions; download that API/.DLL and use it to work with the database.

Accessing An API

The typical way to access an API is inside the development environment. A large many programmers use Microsoft Visual Studio, as do I on a daily basis. Inside Visual Studio while I’m working on my code, I browse and add a "reference" to an API. In this case, let’s access tools from/for Adobe Reader.

In Visual Studio you right click References then choose Add Reference and browse to the API we want to take advantage of. Once we do, it’s in our project.



Now you have access to a set of Adobe commands, in this case, some Adobe forms. I just type the "using" clause to be able to reference the APIs functions in this section, then see where I can type "AdobeExample.Form1" to create an instance of a form. We’ll stop here, just to give you an idea of how this works.



Let’s Mention SDKs

I don’t want to sidetrack us too much, but there are also things known as SDKs ("Software Development Kit") which, for our purposes, is a kit or collection of APIs for a group or specific large application (like the Adobe SDK, Autocad SDK, etc.).

OK, I mentioned it; now, back to our example.

Practical Example - Adobe

Most of the necessary APIs are already downloaded when you install a new application. Let's think about Adobe Acrobat Reader as an example, you use it to read .PDF files. When you install Adobe, it unpacks a lot of their DLLs into your designated folder (often C"\ProgramFiles\Adobe\...).

Acrobat Reader uses the operating system APIs plus the Acrobat application code installs their own API files (e.g. .DLLs). Not only do Adobe’s applications use these APIs, but they are available as a "reference" to any programmer (as we’ve seen by browsing above). In our screen caps above, we referenced the Adobe APIs in our source code and now we can do a bunch of PDF-specific things in our application. This is a classic API. We never see Adobe's source code, but they have made hundreds of functions and objects available to us.

How Do You Learn How To Use Each API?

I probably shouldn’t have admitted how often developers Google information in a previous blog post, but Google is the best place to start. Most major apps like Google Earth, YouTube, Autocad, Excel have entire sites documenting their API commands you can use. By and large, they do a great job of it.

Additionally, within MS Visual Studio while you’re coding there are lots of auto-complete Intellisense features, and right-click "Go to defintion" actions you can look at within your development environment that also give you clues to what you need to do to use the API commands. It’s pretty sweet.

The Takeaway For Non-Developers

When your development team is talking about interacting with some app, now you know that those apps’ APIs are your developers’ way in. Just right there, that makes you more knowledgeable than most people in non-programmer positions. This is your jumping off point in the planning stages. Have your developers walk you through the advantages and pitfalls of the possible APIs you can use.



Continue reading Part 4 - Web Services, APIs)