Now, any machine requires a control panel. You don't have to understand how the machine itself works in order to operate the machine, as long as you understand how to use the control panel. The control panel will include a way to specify the input (the raw materials of the machine plus any control settings), the output (the stuff you want the machine to produce). The API **of a given routine** is a completely unambiguous description of the control panel, such that the everything required to operate the machine is described so precisely that not only can the description allow a human to run the machine, but so could a robot (i.e., it is not enough to say "look for the steering wheel", instead you say "the steering wheel is controlled in these ways and is found at this exact location".

So, every routine has a control panel that is its API; control panels can be very complicated with many buttons, dials, input slots and output trays for a complicated machine with many functions, or very simple, with one input, one output, and one button for a machine with one function. Just because the API is simple, doesn't mean the machine is: imagine a machine that takes in only hydrogen, but when you press the button it it uses star trek technology to build a complete car :)

Now, coding is tricky and good routines are hard to produce, hard to debug (make sure they are free from errors), and hard to maintain (keep working in the face of changing environments). What makes a routine "good" we can ignore for now, but it changes depending on what you are doing :)

So, since writing, maintaining and improving software is time-consuming, it is very important that every programmer does not have to start programming from scratch, regardless of programming language. Therefore, programmers make collections of routines available to other programmers so that each programmer does not have to reinvent the wheel. These collections of software can be called various things; in my field they are called "libraries", other places they are called "packages"; when they have a special relation to the language or platform they can be called "system libraries" or "standard packages" or so forth, but none of these distinctions really matter to understanding APIs.

At some point a programmer (or group of programmers) will wind up with a lot of machines that handle work typically needed in certain types of operations. They will then organize all these routines into a collection to be packaged for others to use called a library or package. Confusingly enough, we then refer to the full list of all individual APIs as the API of the collection. Then, programmers can read this collection API document in order to understand what functionality the collection offers and how to operate all the bundled machines, without having to build all these machines for themselves.

We can build these collections of routines into very complicated hierarchies with many collections collected at each level of the collection hierarchy. If we do this, we will refer to the sum total of all the APIs in the hierarchy of collection as the API of the whole hierarchy of the collection.

Therefore, you see that API is a complicated concept depending on which level of API you are referring to at the moment. Because none of the people "explaining" this really understand it, you get a lot of confusing, seemingly contradictory information on this stuff. To make things make sense, you need to first indicate what level of API you are talking about, but doing so requires people to understand a lot of context that nobody actually has. Even geeks only rarely think this specifically when we say "API", since the other programmers can figure out what we mean by the context of our discussion.

[ Reply to This | Parent | # ]

[ Reply to This | Parent | # ]

[ Reply to This | Parent | # ]

Sorry, but I don't think you've gotten the salient issue. (Oracle has concocted a weird gumbo, either to confuse the jury, or because they aren't sure where their claim becomes valid.)

Google wanted to provide a developer environment for its platform. It could have started from scratch (which it has for the Go systems language), but that would mean the developer community would have to learn a new language and new idioms. As the platform was unproven, there was a chicken-egg problem: developers won't write applications in a new language for a new platform unless there's a good likelihood of returns for the costs. But, without applications, platforms are unlikely to become popular.

So Google looked around and decided that java was the language that had wide adoption and was designed in order to abstract away the architecture, to the degree possible, and the operating system.

I liken the java apis to a dictionary, though perhaps telephone book would be closer. Each package would be akin to a book's section showing all people with listed numbers whose last name begins with the same letter. Each method would be an individual listing. Look up a name, find the number, put that into the telephone, and a connection is attempted.

Clearly, it's now metaphor-stretching time, but Google wished to build a town and provide a phone book, but the town had to have many of the same listings, because... well, the developers have autodialing already set up and they resist when asked to change them. Clearly there has to be copying of the first phone book in order to wire up the telephony in the new town so as to not break the developers' autodial. These developers rarely call certain numbers, but call other numbers all the time. The entirety of the phone book need not be copied, but there are numbers which have to be exact matches and found in the exact same spot for developers who are familiar with the names in the first phone but who need to call someone not in their autodialer.

Using the phone book to make a contact list? No issue. Independently wiring up another town? No issue. Copying of one entry? No issue. Copying of many entries with a different organization, probably no issue. But, as this would be akin to taking classes and changing package names, the autodialers break and the developers who are familiar with the old town's phone book have to work harder to find where the listing they need is now located. Again, Google's goal was to minimize incompatibility of their platform with existing code and to not impose a significant learning curve for developers.

We know that Google didn't copy the whole phone book, so the question of infringement is not in play for that. And we know that it copied substantial parts of sections of Sun's phone book. Not the town's wiring, but many of the towns' key listings using Sun's organization, which Google needed to wire its town and assign numbers so the developers could make almost all of the calls they would need to make in the new town. The Judge, informally, dismissed Google's hinting that their copying was "de minimis" which is allowed under fair use.

So, regardless of what else is in the gumbo (speaking of mixing, a propos of my metaphors), there is something that Google did and Oracle has to convince the Judge and jury that it could be considered infringement of Oracle's rights and Google has to convince the Judge and jury that the copying was allowed because the items copied cannot be protected, or Sun/Oracle waived their rights to the phone book's organization, or Google's use is allowed under fair use doctrines.

Assuming, of course and harrumph, that Oracle didn't muff their description of the copyright registration and make all our meditations moot.

[ Reply to This | Parent | # ]

[ Reply to This | Parent | # ]

[ Reply to This | Parent | # ]

• an API - Authored by: Anonymous on Tuesday, May 01 2012 @ 07:15 PM EDT