What is an API?

Question.jpg

First... it is an acronym API is an acronym which means Application Programming Interface.

What is it?

It is a contract that allows computers to talk to each other. Another name used widely is a protocol which is a set of rules that must be followed to exchange information. By "talk", I mean the ability to ask a question and get a valuable answer back.

How does it work?

A really smart computer person (a developer) defines and builds a system that accepts questions (request for information). Next, that same developer writes instructions (the contract or protocol) that must be followed in order to properly accept questions so that the valuable answers can be computed and returned. Another developer, somewhere else in the world, reads the fascinating and tantalizing contract documentation. She then sets out to build a unit within her own system to ask questions at the proper time. Her system then uses the subsequent answers to deliver great value to that system's end users.

What should be in an API's contract?

1) Location, Name and Protocol

  • Mechanism or protocols to be used to establish a connection. These are typically another lower level type of API or contract.
  • The address or location of the system that can answer the questions.
  • Name of the service.

Let's give an example of a typical business to business (B2B) scenario. Just below is a URL or web address used to locate a service which finds nearby pizza delivery services.

http://www.pizza-store-locator.com/service/find-the-closest-pizza-delivery

The protocol used is established with the text: "HTTP". HTTP is another acronym which stands for Hypertext Transfer Protocol. This is another contract which specifically defines how a web browser, like FireFox or IE, can communicate with a web server. Many higher level business services are built on top of this lower level API.

The location of this API is defined as "www.pizza-store-locator.com". This type of string is typically called a domain in web parlance.  A domain is always associated with an IP address. This is a unique identifier and allows request to be reliably routed to the appropriate web server. An IP address is an acronym meaning "Internet Protocol" address. There is that word, "protocol", again. The whole WWW, World Wide Web, is just a series of layered protocols that allow everyone to talk to everyone else.

The name of the  service is "service/find-the-closest-pizza-delivery". This name is mapped to business logic, or a program, on the web server in this case that is responsible for formulating an answer. Just guessing, but this service probably helps find pizza delivery services. It is nice when the name of a service is self describing!! That is the sign of a good API.

2) Input Definition

  • What questions can be asked?
    • Is there only one questions or different types of questions?
  • What are all the pieces of information that must be included in the question so I can answer it?
    • In the example above, for the pizza delivery service, what information is required to find the closest pizza delivery shop? The contract could specify an address is required like 90 Broad Street, Suite 2002, New York, NY.  But it could also just be a latitude and longitude.
    • Lets keep going... how far away are you interested in searching? 5 Miles, 10 Miles or do you care? No, you don't because it is not you that must do the driving to the pizza shop so... perhaps you only want a certain number of shop results back like 20 or 5? Perhaps you do need 20 but want to have at least 5 different pizza shop options returned so you can get a good selection.
    • All this stuff needs to be defined by the service creator based upon research by a product manager into how people actually think and what they want.
  • How should all of those pieces of information be structured?
    • There are many ways to send information to the service.

3) Outputs

  • A description of the answers that can be returned
  • Format of the answers
  • Exceptions or errors that can be expected
    • A good API will defined all of the possible bad scenarios that can occur and how it will notify the calling program. This allows the calling program to respond gracefully.
    • Here are some examples to possible bad return results:
      • Not enough information was submitted, and here is specifically what was missing: the latitude.
      • The service is temporarily down.
      • The service is too busy, please try again later.
      • No results were found.
      • Results were found but not as many as you asked for because we only search within a maximum distance of 10 miles
      • This service has moved to a new address...
      • ...and so on...
    • Typically each of the possible errant answer is give a unique identifier or code which allow computers to respond easily.

An "out of this world" example...

https://mail.google.com/a/onboardinformatics.com/?ui=2&ik=a5e739f4ac&view=att&th=126ae7ba99fb9786&attid=0.2&disp=inline&realattid=f_g5fhyblt1&zw

Do you remember "Close Encounters of a Third Kind" when the scientists first started communicating with the huge alien ship that came over the mountain? Sure you do... who can forget this brilliant movie that is now such a fundamental part of the fabric of our existence. Well... in this movie, the scientist use mathematics manifest through sound and lights to try to establish basic communication with the aliens. Once the alien understood, they repeated back the message to say to the scientists, quite loudly, "Yes, we heard you!" An interface was established, an agreement that if you flash your lights and send over sound waves, we will capture that information, process it, and send you back beeps and blips along with flashing light signals too (and the result of this will be that we land our ship and change the very nature of your lives!).

https://mail.google.com/a/onboardinformatics.com/?ui=2&ik=a5e739f4ac&view=att&th=126ae7ba99fb9786&attid=0.3&disp=inline&realattid=f_g5fhyblv2&zw

References

I have listed some common websites to give other definitions of an API; however, they commit some of the cardinal sins when defining a entity.

1.     Wikipedia

  1. Sin! - They use the object in the definition itself.

2.     How Stuff Works

  1. Sin! - They use the noun in the definition itself.
  2. And worse still they limit the definition of API's to web technologies.  It is important to understand that API's are EVERYWHERE... for example... inside a computer, API's are established to allow software to run  successfully on a computer's hardware which has nothing to do with the web.

Image Credit: Colin Kinner on Flickr.com