So working as a web developer, I work with a lot of APIs. I’m also frequently asked things by non-coders about our API and the APIs of other sites. The concept of API seems to be that of some magical coding device that solves problems. However, while this is an amusing concept, it’s not entirely correct. In trying to explain the details of this to a coworker the other day, it occurred to me that I needed a good parable. So here you go:

Imagine if you would, a grouping of small islands in the middle of an ocean. Many islands are rich in coconut trees, but one is favored by schools of fish for it’s shady rock outcroppings near shore . Between these islands are a number of conveyor belts, capable of holding a small amount of weight. Each island is inhabited by a single individual. The islands are too far apart for speech, and they have long since run out of anything to write on, so the individuals are left to communicate by a pre-agreed upon system. They send across pebbles on the conveyor system, with different numbers corresponding to different messages. An example exchange:

1 Red rock + 2 Blue rocks = What kind of fish do you have today?

1 Red + 1 Green = 1 Cod + 1 Tuna

2 Red + 2 Green = **Bad data — not translatable** — (Should a non-agreed upon message be passed, it will not be understood)

4 Green = Message not understood. Please resend

1 Red + 2 Green = I’ll take the Cod please

2 Blue + 2 Green = Will do, please send 2 coconuts in exchange

Now this is of course a simple nonsense exchange, and it’s not very intuitive system, but in creating a communication system which allows them to exchange information over the conveyor belt (which is our metaphor for the copper or fiberoptic lines of the internet, these men have created an API. In it’s simplest sense, and API is a predefined system for communication, allowing two parties to share information. While many API share similarities, each data provider is free to set up their API however they want, both in terms of how the requests are made and how they respond to requests.

As you can see, there’s nothing magical about this. In a practical sense, any data that your company or site wants to allow others to read or write can be built into an API, some takes longer than others to expose in an intelligible manner. For example, a request to “give me the username and email for a user with id=300” is simpler than something like “give me the social graph of usernames connected to the user with id=300.”

Obviously, providing your data in such a manner could be a security problem, so often times API’s will be locked down to only users or other sites making requests with appropriate keys or perhaps the site providing the API will limit the number of requests per hour. There are a number of technical considerations that can are are made in designing an API, but I’ll save you from and other complications here.

Hope that helps. Feel free to post question in the comments, and I’ll try to explain.