|
Authored by: Anonymous on Thursday, April 26 2012 @ 10:16 AM EDT |
UNDERSTANDING ROUTINES AND APIs
Code is organized into routines
(also called functions, subroutines or
methods). A routine can be thought of as
a machine that performs some
required operation for the user. Building
extremely complicated machines
directly is too error prone, so complicated tasks
will be broken down into
a series of simpler tasks, all of which can be
performed by a given simpler
machine.
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 | # ]
|
|
Authored by: marcosdumay on Thursday, April 26 2012 @ 10:22 AM EDT |
n/t, but also IANAL. [ Reply to This | Parent | # ]
|
|
Authored by: Anonymous on Thursday, April 26 2012 @ 12:15 PM EDT |
I think it might be more simple to describe an API as a
conceptual contract. It is a contract in the sense that if
a programmer does X, they can be confident that Y will
happen.
I say that it is conceptual because the contract could be
described in many different but equivalent ways. I just
mention this because a legal contract tends to refer to a
specific sequence of words that one could conceivably
copyright. Because of the precision of computer algorithms,
it is possibly to describe the same API contract in lots of
different equivalent ways. [ Reply to This | Parent | # ]
|
|
Authored by: Anonymous on Thursday, April 26 2012 @ 12:59 PM EDT |
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 | # ]
|
|
Authored by: Anonymous on Thursday, April 26 2012 @ 08:31 PM EDT |
bulls eye! great analogy. [ Reply to This | Parent | # ]
|
|
Authored by: tinkerghost on Thursday, April 26 2012 @ 10:02 PM EDT |
Actually, I though about this this morning.
Oracle has repeatedly tried to describe APIs as blueprints, but that's not
accurate. A blueprint describes everything down to the last detail - IE, the
wiring passes through the floor up the wall to the outlet not down from the
ceiling. The API's on the other hand simply dictate that there be an outlet on
that wall 12" above the floor & 3' from the corner.
In that sense, the APIs are the bid specifications that a company would shop
around to different architects to get blueprints made. I'm fairly certain that
copyright law doesn't consider the blueprints 'derivative' works of the bid
since the components used from the bid are purely functional.
---
You patented WHAT?!?!?![ Reply to This | Parent | # ]
|
- an API - Authored by: Anonymous on Tuesday, May 01 2012 @ 07:15 PM EDT
|
|
|
|