What is an API for complete idiots like me?

Why it is important and how to get started working with them? Please provide non technical analogies as I already have tried but don't understand them.

Comments

[Austin S. Hemmelgarn]

Quite simply, an API is a set of clearly defined rules for how to interact with something.

As an analogy, think for a moment about doors. There are some pretty specific ways you can interact with a door. Suppose you have a hinged door with a deadbolt lock and a latch operated by a rotating handle that has it's own integrated locking mechanism (essentially, what you might expect to find in many parts of the world as the front door of an apartment or a house). With such a door, you have the following properties that are inherent to the door:

• How far open the door is.
• Whether the deadbolt is locked or not.
• Whether the handle is locked or not.
• Whether the door is latched or not.

And you have the following possible interactions:

• You can observe how far open the door is idempotently (that is, making this observation will not change how far open the door is).
• You can observe whether the door is latched or not, but this may change how far open the door is (if the door is 'closed' but not properly latched, checking if it's latched may cause it to swing open).
• You can observe whether the deadbolt is locked, but only if the handle is not locked or the door is open.
• You can observe whether the handle is locked, but this may cause a door that is closed and latched to no longer be latched (because you have to try and turn the handle to check if the handle is locked or not).
• You can attempt to open the door if it is not open, but this will fail if the door is latched.
• You can attempt to close and latch the door if it is open, but this will fail if the deadbolt is locked.
• You can attempt to close but not latch the door if it is open, but this will also fail if the deadbolt is locked.
• You can attempt to unlatch the door if it is latched, but this will fail if the handle or deadbolt is locked.
• You can attempt to lock or unlock the handle, but this will require you to provide a key for the handle.
• You can attempt to lock or unlock the deadbolt, but this will require you to provide a key for the deadbolt.

That list of properties and possible interactions is, in essence, an API for interacting with this door. The interactions themselves are methods or functions, and the properties may take on various form depending on the exact nature of the API (they may be actual properties, or they might be accessed through special 'get' methods, or some could even just be included automatically as part of the result of using any of the other methods).

Having a well defined set of interactions like this is really important in life in general, not just programming, because it ensures consistency of results. Think for example of how we rely on the 'API' of basic physics every day to go about our lives. If gravity suddenly stopped working, or only worked if you did certain things, life would be really hard.

As far as actually using them, if you're doing any sort of programming, you already are, you just aren't thinking about it. A programming language, is, itself, an API. It defines how you tell the computer to do what you want it to do so that you can get the results you expect. For example, if you do front end web development, then the stuff in JavaScript that you use to interact with the actual HTML of the web page is an API.

[Shamima Hossain]

Omgosh...thank you so much for your effort to make such a detailed explanation. I think I'm getting an intuitive feeling of APIs now