API: The Convenience Store Clerk of Software

Difficulty: Easy

Do you recognize this friendly face? Apu from the Simpsons, can teach us a lot about a a profoundly important construct in the software world, the Application Programming Interface (API). APIs are found in virtually every software program, and they are responsible for delivering a significant portion of application functionality, especially it today’s world where many applications are distributed and function on the World Wide Web. So how can Apu help us understand what an API is? Even though Apu graduated top of his class of 7,000,000 in Computer Science at Calcutta Technical Institute and holds a PhD from Springfield Heights Institute of Technology, his grounding job responsibilities at the Kwik-e-Mart are what really can teach us about the working characteristics of an API.

So what is an API? Wikipedia says it’s a set of subroutine definitions, protocols, and tools for building application software. This is somewhat ambiguous, but not to worry, Apu can help us understand more about what exactly this means. Apu’s job functions and interactions behind the counter (interface) at the Kwik-e-Mart mirror the functions and characteristics of an API.

If I had to simplify the job function of an API, I’d say that it is the software equivalent of someone who provides a service. Apu provides several services to his customers, just as APIs provide services to its “customers” (which happen to be software programs). It is the means by which these services are provided that the “set of subroutine definitions, protocols, and tools for building application software” are applied. I’m going to break-down this definition of the API into the three separate categories, covering subroutine definitions, protocols, and tools separately.

Subroutine Definitions

Let’s first take a look at subroutine definitions, which are basically a set of instructions that, when followed, provide a service. In Apu’s case, for example, these definitions are the instructions on how to grab a pack of cigarettes from the shelf, or ring-up the total bill of purchased items. For getting the cigarettes, Apu’s subroutine may look like this:

  1. Request identification from customer.
  2. Confirm that customer is above 18.
  3. If below 18, respectfully deny purchase of the cigarettes.
  4. If 18 or above, walk to the shelf behind the counter.
  5. Pull desired cigarettes from the shelf.
  6. Walk back to the counter, and place cigarettes down.
  7. Proceed to the ring-up subroutine.

Subroutine definitions, like the one above, lay the groundwork for specifying how an API will actually know how to provide the service. These definitions can actually involve the use of other subroutines as the building blocks to create intricate, more complicated service offerings. For Apu, his “clean the store” subroutine may involve the “sweep the floor,” “wash the windows,” and “turn off lights” subroutines.

Protocols

Next-up is the protocols. Protocols are essentially a set of rules that must be followed in order to interact with the API. In Apu’s case, the protocols that must be followed include, (but certainly not limited to):

  • All alcohol must be purchased by a client over the age of 21 with valid ID.
  • All tobacco must be purchased by a client over the age of 18 with valid ID.
  • All clients must speak in either English or Hindi in order for requests to be understood.
  • All payments must be made with currency in USD.
  • To order a hotdog, say something along the lines of, “May I please have a hotdog.”

These rules help customers understand how to get the services they desire at the Kwik-e-Mart. If customers wants to purchase alcohol, they better be over 21 and bring their current photo IDs. In the software world, it is important for developers, who want to use an API, to understand exactly how to interact with it; the protocols of the API provide that information to the developer. With software, these protocols are usually specified in documentation that is provided by the developer that made the API. As an example, you can find the Twitter API documentation here. If you go to that page, you’ll see that there is information regarding how to authenticate (“login”), what rules apply for rate limiting (how much and how often you can ask for services from the API), and client policies, which put restrictions on the usage of the API. For the Apu API, we have restrictions on the sale of alcohol and tobacco, but we also have the rules for how to actually initiate the subroutines defined in the API. To kick-off the “get hotdog” subroutine, the customer first has to ask Apu, “May I please have a hotdog.” This protocol would clearly be defined in the Apu API documentation (if it was maintained by the developer appropriately).

Tools

Finally, we have tools. This is probably the easiest facet of the API definition to understand, and it probably doesn’t even need an analogy. (I’m going to give one anyway.) In order for Apu to facilitate his job successfully, he employs the use of tools to complete the services that he provides. To get a hotdog from the hotdog roller, he might need to use gloves and a pair of tongs. To get something off the top shelf behind the counter, he may need to use a step-ladder. To ring-up a customer, Apu needs to use a cash register to store the money and calculate the total cost of purchases. The tongs, step-ladder, and cash register are examples of the tools used in the Apu API. In the software world, tools typically mean other pieces of software or hardware. For developers, rather than re-inventing the wheel for certain tasks, they may choose to use software that was written by someone else, perhaps to send an email, display a map, or play a video. These tools assist the API on successfully providing its services.

Conclusion

The combination of subroutine definitions, protocols, and tools result in a functioning API. All-in-all, APIs are programs, or bits of programs, that provide some kind of service. The service offerings are facilitated by receiving a request from a software client (customer), using the subroutine definitions and tools to execute the service, and then providing a response back to the client or customer. For the Apu API, this response is almost always, “Thank you, come again!”

It’s All Greek to Me: A Review of Code

Difficulty: Easy

What if I told you that you know how to code? It’s true, and the reason that I know this is that you are able to read these sentences right now. You may not be able to hack into a computer mainframe or tell a robot how to smile, but you can code none the less. What’s even more impressive is that it is impossible to understand or communicate without knowing how to code.

So what do I mean when I say “code?” I must not mean the ability to tell computers how to function, otherwise I would have already lied to you. I’m not lying, so allow me to clarify:

Code = a representation of information

It’s really that simple (and beautifully simple at that). With this definition, it is easy to see that the English language is a code. The letters, words, subjects, predicates, sentences, and paragraphs that compose the English language allow us to convey, or represent, information in a common way so that information can be disseminated between two or more parties. It is in this common ground that we see the purpose/importance of code. It is used as THE medium to communicate. Without it, our society would be stuck in a time well before the dark ages.

Continuing with this definition of code, we can realize that as humans, we use several different codes to convey similar information. Each of these codes has a different purpose and effect, but can communicate the same concept given the right context. Let’s take the simple idea of an apple as a thought exercise. As an English-speaking person (that may have a deaf and a blind family member), I can communicate the concept of an apple in several different ways:

Encoding: Image

Encoding: Text

Apple

Encoding: Sound

Encoding: Sign Language

Encoding: Braille

⠁⠏⠏⠇⠑

Each of these representations above is different, but all describe an apple. You may have noticed that I snuck a word that you may or may not already know.

Encoding = the attribution of a specific code to information

We can encode any type of information. This information can be anything, such as data, ideas, pictures, sounds, and actions. I can also encode anything with anything. For the sake of argument, let’s come up with a new encoding of the English alphabet.

A B C D E F G H I J K L M
N O P Q R S T U V W X Y Z

I have attributed (encoded) random symbols to each letter of the alphabet, and in doing so, I can now freely communicate in this new code.

                        

This all seems simple enough, but what benefit does this have other than being able to pass tediously-written notes between friends in middle school? Well, the beauty of encoding really comes into play when we “randomly” assign meaning to electricity flowing through wires. You may have heard before that computers “only understand zeros and ones.” (This is otherwise known as “understanding Binary.”) This actually isn’t true, because computers don’t “understand” anything, rather, we as humans personify the idea of electricity flowing through specific circuits of a computer so that we can understand how they work. So what are zeros and ones? Simply put, they are an encoding that we attribute to the concept of whether or not electricity is flowing through a circuit.

Concept Encoding
Electricity not flowing through a circuit 0
Electricity flowing through a circuit 1

This encoding can then be capitalized to represent more and more complicated concepts. One of these more complicated concepts is that of the opcode, which is the encoding of a command on a set of concurrently on or off circuits. Opcodes are the basis of the most fundamental computer programming languages, and they can be combined in a specific pattern to ultimately create what we know as a computer program. As an example, let’s write a program for the dumbest “computer” of which I can think – the light-switch.

Opcode Command
0 Turn off the light
1 Turn on the light

If I wanted to make a program for my light-switch computer that flickers the light on and off four times, the program would simply be 10101010. When I input these opcodes (commands) in sequence to the light-switch computer, the computer will output a light that is on, then off, then on, then off, then on, then off, then on, then finally off. Yay, we’ve just written one of the most useless programs!

How about something slightly more interesting. Let’s create a program for our light-switch computer that communicates an S.O.S. distress signal in Morse code; S.O.S. in Morse code is “… _ _ _ …”. For our light-switch computer, the program would be 1010100011011011000101010. Excellent, we now have a slightly more useful program if we were to get stranded on a desert island with our flashlight computer!

For the sake of brevity, I won’t go into any more detail about the more complicated code and computer circuit paradigms that are used to build a computer; however, I would like to recommend future reading if you are interested in this topic.
One of the best books that I have found on bridging the gap between electricity and the inner workings of modern-day computers is called Code: The Hidden Language of Computer Hardware and Software by Charles Petzold. In this book, Petzold does a fantastic job at logically building a computer from ground up by starting at the fundamentals of code, logical circuit design, and data. The book also gives a great history of the origins of computers and coding languages, ultimately resulting in a book that creatively blends both narrative and technical specification to make the concepts understandable. It’s not the easiest read you will find, but it’s one of the easiest reads with material this complicated.

Keep coding!