decoration decoration

When you want to know more...
For layout only
Site Map
About Groklaw
Legal Research
ApplevSamsung p.2
Cast: Lawyers
Comes v. MS
Gordon v MS
IV v. Google
Legal Docs
MS Litigations
News Picks
Novell v. MS
Novell-MS Deal
OOXML Appeals
Quote Database
Red Hat v SCO
Salus Book
SCEA v Hotz
SCO Appeals
SCO Bankruptcy
SCO Financials
SCO Overview
SCO v Novell
Sean Daly
Software Patents
Switch to Linux
Unix Books
Your contributions keep Groklaw going.
To donate to Groklaw 2.0:

Groklaw Gear

Click here to send an email to the editor of this weblog.

Contact PJ

Click here to email PJ. You won't find me on Facebook Donate Paypal

User Functions



Don't have an account yet? Sign up as a New User

No Legal Advice

The information on Groklaw is not intended to constitute legal advice. While Mark is a lawyer and he has asked other lawyers and law students to contribute articles, all of these articles are offered to help educate, not to provide specific legal advice. They are not your lawyers.

Here's Groklaw's comments policy.

What's New

No new stories

COMMENTS last 48 hrs
No new comments


hosted by ibiblio

On servers donated to ibiblio by AMD.

Trying to explain APIs to non-geeks | 287 comments | Create New Account
Comments belong to whoever posts them. Please notify us of inappropriate comments.
examples of APIs that almost everyone uses:
Authored by: Anonymous on Wednesday, June 05 2013 @ 03:53 AM EDT
A really simple example, which is not oversimplifying:

The QWERTY keyboard *layout*.

[ Reply to This | Parent | # ]

Trying to explain APIs to non-geeks
Authored by: Anonymous on Wednesday, June 05 2013 @ 06:44 AM EDT

Here's my attempt at a non-geek friendly explanation of APIs:

The purpose of an API is to make a clear offer of the available functionality provided by a piece of computer code. It is somewhat analogous to a restaurant's menu which presents a list of available dishes and their prices.

The restaurant customer (the API caller) will make a request for specific items off the menu to a member of waiting staff who will eventually return with the ordered food, or possibly an apology that the restaurant (the implementation behind the interface) cannot fulfill the order at this time (because they have run out of necessary ingredients or some other problem).

All the complexity of running a restaurant is hidden from the customer - they don't need to be a top chef who knows just the right balance of ingredients to get the best flavours; they don't need to worry about the timing of producing the dishes so that each table's order arrives together but also ensures that all other customers are served in a reasonable time; they don't need to worry about the supply chain so that fresh food is always available or the staff rota so that there are enough staff working during particularly busy periods.

Similarly, the user of an API for a computer library need not worry about the precise implementation details of the library, they can simply make the necessary API calls and rely on the library to complete the requisite tasks to perform the operation - the API user can remain thinking at a relatively high level ("I would like a meal") while the library deals with the low-level details such as memory management, resource contention, etc. (how to produce the ordered meal). (C.f. s eparation of concerns)

It is conventional, and users expect, that the menu be structured in a particular way, e.g. starters are listed first, then main courses, then desserts, with drinks at the back, and that certain symbols are used to identify vegetarian options, etc. However, the reputation of the restaurant will be based on the creativity of the chefs, the quality of the food and the ambience of the restaurant i.e the implementation. This is also true with computer programs which have standard libraries that all present substantially similar interfaces even though the implementation behind the API might be very different. Like restaurants, the successful libraries are the ones that are both quick and have the least bugs - "Waiter, there's a fly in my soup!".

[ Reply to This | Parent | # ]

Every piano would need a different keyboard n/t.
Authored by: Anonymous on Wednesday, June 05 2013 @ 08:34 AM EDT

[ Reply to This | Parent | # ]

Nitpick -- Lego, not Logo N/T
Authored by: lnuss on Wednesday, June 05 2013 @ 08:56 AM EDT

Larry N.

[ Reply to This | Parent | # ]

Trying to explain APIs to non-geeks
Authored by: tknarr on Wednesday, June 05 2013 @ 04:29 PM EDT

Yep, the "incompatibilities" in the Java APIs on Android are the removal of things like the AWT and Swing UI toolkits. Sure, it means that code written for Java that uses those can't be directly compiled for Android, and in that sense it's incompatible. But the kinds of UI layouts those toolkits create don't work on the small touch-screens of a cel phone. Anyone wanting to port applications over would have to rework the UI completely anyway using a different UI toolkit to get something that'll fit the screen size and input methods, so the lack of AWT and Swing doesn't really matter.

It's like complaining that an automatic transmission car's controls aren't compatible with a stick-shift's because it's missing the clutch pedal.

[ Reply to This | Parent | # ]

Trying to explain APIs to non-geeks
Authored by: darkonc on Wednesday, June 05 2013 @ 08:22 PM EDT
I think that what you're pointing to is "Portability".

i.e. I can take the code for an app that I wrote back in the '80s for an old Sun 1 (serial #300) with a Motorola 68010 and 256KB of RAM, and still compile and run it on my dual-core Intel with 4GB of RAM. The reason why I can do that is that -- although the operating system and hardware has changed, the APIs have remained backwards compatible.

If you were to declare that APIs are copyright, then the last 30 years of code (C, C++, etc.) would become illegal -- because C was designed by Kernigan and Ritchie, but I don't think that they've done an implementation of C (or it's derivatives) since the late '70s. Nonetheless, may (most) of the API's they designed have survived through countless re-implementations and rewrites.

Powerful, committed communication. Touching the jewel within each person and bringing it to life..

[ Reply to This | Parent | # ]

Trying to explain APIs to non-geeks
Authored by: Anonymous on Thursday, June 06 2013 @ 03:43 AM EDT
Dalvik vs. Java
I can confirm that your description is accurate.
Dalvik omits to implement some portions of the Java API,
that doesn't make much sense on a mobile device. Like Java's
swing API (everything under javax.swing.*), which is an API
for rendering GUI components like buttons, text, listboxes
etc., Swing isn't designed with small screens in mind.
Other parts of Dalviks API are fully compatible.
Oracle's concern is that this would cause the same kind of
fragmentation that Microsoft's EEE (Embrace Extend
Extinguish) attempt would've caused (was thwarted by
trademark law), while not really a legitimate concern it's
easy to understand how their lawyers might get "confused"
and believe they HAD to stop Dalvik.
I wonder if Sunacle might also be frustrated that J2ME never
took of.

[ Reply to This | Parent | # ]

How about this?
Authored by: Ian Al on Thursday, June 06 2013 @ 11:46 AM EDT
An API is text provided to explain to a programmer how one program can provide a
number of processing functions to another.

The programmer wishing to use the computing functions of the API-documented
program, reads through the API list of function names and the definition of the
named functions.

When the required function is identified, the programmer arranges (by using the
programming language features) for his program to pass the data to be processed
to the receiving program together with the name of the required processing

The API also shows how the processed result, if any, is passed back to the
calling program.

The API is written such that the computer language being used by the programmer
includes the features necessary to obtain the computer functions listed in the

Ian Al
Software Patents: It's the disclosed functions in the patent, stupid!

[ Reply to This | Parent | # ]

Trying to explain APIs to non-geeks
Authored by: OpenSourceFTW on Thursday, June 06 2013 @ 12:49 PM EDT
I thought of an API in terms of Lego(TM) baseplates.

Dvalik is like a baseplate from MegaBlocks: compatible (mostly) with Lego
bricks, permitting you to build on it in pretty much the same way as you build
on a Lego baseplate (this assumes that Megablocks is not using Lego's patented
brick locking mechanism). Your castle will appear pretty much the same
regardless of the baseplate manufacturer.

The analogy of this case would be Lego suing Megablocks over being compatible
with their bricks.

[ Reply to This | Parent | # ]

Groklaw © Copyright 2003-2013 Pamela Jones.
All trademarks and copyrights on this page are owned by their respective owners.
Comments are owned by the individual posters.

PJ's articles are licensed under a Creative Commons License. ( Details )