decoration decoration
Stories

GROKLAW
When you want to know more...
decoration
For layout only
Home
Archives
Site Map
Search
About Groklaw
Awards
Legal Research
Timelines
ApplevSamsung
ApplevSamsung p.2
ArchiveExplorer
Autozone
Bilski
Cases
Cast: Lawyers
Comes v. MS
Contracts/Documents
Courts
DRM
Gordon v MS
GPL
Grokdoc
HTML How To
IPI v RH
IV v. Google
Legal Docs
Lodsys
MS Litigations
MSvB&N
News Picks
Novell v. MS
Novell-MS Deal
ODF/OOXML
OOXML Appeals
OraclevGoogle
Patents
ProjectMonterey
Psystar
Quote Database
Red Hat v SCO
Salus Book
SCEA v Hotz
SCO Appeals
SCO Bankruptcy
SCO Financials
SCO Overview
SCO v IBM
SCO v Novell
SCO:Soup2Nuts
SCOsource
Sean Daly
Software Patents
Switch to Linux
Transcripts
Unix Books

Gear

Groklaw Gear

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


You won't find me on Facebook


Donate

Donate Paypal


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

STORIES
No new stories

COMMENTS last 48 hrs
No new comments


Sponsors

Hosting:
hosted by ibiblio

On servers donated to ibiblio by AMD.

Webmaster
Oracle v. Google - Day 4 Filings; Why Are APIs Hard to Develop? ~mw
Friday, April 20 2012 @ 10:00 AM EDT

Day 4 produced little in the way of filings. Interestingly, Oracle did not file an updated witness list despite the fact that they have burned through a number of the witnesses on their last filed rolling list of witnesses. It's not that they are likely to get through all of the remainder on their last posted list before the end of today's session, but the Court's orders are that each party is to maintain a rolling list of its next ten witnesses to be called.

The parties did file a joint stipulation on the "deemed unidsputed issue" requested by Oracle and allowed by the Court with respect to the relationship between the APIs in Java and those in Android. (945 [PDF; Text]) The stipulation calls for the jury to be told that they are "substantially similar," with Oracle reserving the right to argue and show that they are virtually identical and Google reserving the right to argue and show that these 37 APIs are only a small part of either Java or Android.

Turning to statements made in the case so far, I would like to draw your attention to two. First, this statement from Michael Jacobs, lead attorney for Oracle, during his opening statement (as paraphrased by our in-courtroom reporter):

Jacobs (Oracle) - When you create something, you file a notice with the Copyright Office to strengthen your right. Then you register and get a certificate.
I really would like to think that Mr. Jacobs knows a bit more about copyright law than this. For example, your copyright arises when your work is embodied in a tangible medium of expression, i.e., you write it down or enter it into a computer. You don't have to file anything with the Copyright Office. If you want to sue someone for infringement, then the work in which you already claim a copyright needs to be registered with the Copyright Office. Such registration does nothing in terms of establishing whether the submitted work is actually protected by copyright except to the extent that it establishes that the work falls into a class of works that may be protected by copyright, e.g., computer software. This statement by Jacobs, which he has repeated on numerous occasions, is simply false, and it only serves to confuse the jury.

The second is covered by these statements taken together about APIs:

Jacobs (Oracle) - It's the design of the APIs that Google emulated.
Ellison says writing APis is 'arguably one of the most difficult things we do at Oracle.'
Let's accept for a second that APIs are hard to write. The question that has not being asked or answered so far is, why are APIs hard to write? Is it because there is so much creative expression necessary to decide how to group and organize the various components that go into the API? Or is it because, in developing an API, one must consider all of the technical elements that need to be addressed: the required inputs, the functions to be performed on those inputs, the outputs to be returned, and the interrelationship of each of those to everything else around it within the code.

From my Red Hat days I recall seeing a chart our engineering staff had developed showing all of the interdependencies among the various modules in Red Hat Linux. It was enough to make your head hurt. Yet, those dependencies and the modular design of Linux are part of what makes Linux such a terrific operating system. You could work on any module independent of the other modules so long as you respected the interfaces and interdependencies that existed among the modules.

I have to believe that this is what drives the difficulty of developing APIs, whether for Java, Linux, or any other software platform. The difficulty is not in how to package them, it is in determining all of these functional relationships. At least, that is my impression, and I invite those of you with far greater insight to chime in on this topic.


*************

Docket

04/19/2012 - 944 - Minute Entry: Jury Trial held on 4/19/2012 before William Alsup (Date Filed: 4/19/2012). Witnessess called. Further Jury Trial set for 4/20/2012 7:30 AM. (Court Reporter Kathy Sullivan; Debra Pas.) (dtS, COURT STAFF) (Date Filed: 4/19/2012) (Entered: 04/19/2012)

04/19/2012 - 945 - STIPULATION WITH PROPOSED ORDER Stipulation regarding selection, arrangement, and structure filed by Google Inc., Oracle America, Inc.. (Peters, Marc) (Filed on 4/19/2012) (Entered: 04/19/2012)


*************

Documents

945

UNITED STATES DISTRICT COURT
NORTHERN DISTRICT OF CALIFORNIA
SAN FRANCISCO DIVISION

ORACLE AMERICA, INC.
Plaintiff,
v.
GOOGLE INC.
Defendant.

CASE NO. CV 10-03561 WHA

STIPULATION AND [PROPOSED]
ORDER REGARDING SELECTION,
ARRANGEMENT AND STRUCTURE

Judge: Honorable William H. Alsup


STIPULATION

WHEREAS, the parties have met and conferred and have reached agreement regarding a statement that Google made in a brief to the Court regarding substantial similarity of the selection, arrangement and structure of API elements in the 37 accused API packages;

NOW THEREFORE THE PARTIES HEREBY STIPULATE AND AGREE as follows:

1. The following statement shall be read to the jury on the same terms as the other statements in the Court’s Order Granting in Part Oracle’s Motion to Deem Issues Undisputed and Denying Relief Regarding Statement to Jury (ECF No. 938):

For the 37 accused API packages, Android and Java 2 SE Version 5.0 have substantially the same selection, arrangement and structure of API elements.
2. This stipulation is made without prejudice to Oracle arguing that the selection, arrangement and structure of the 37 API packages are virtually identical between Android and Java 2 SE.

3. This stipulation is made without prejudice to Google arguing that the 37 accused API packages in Android and Java 2 SE are only a small portion of the Android and Java platforms, respectively, as a whole.

ORDER

The foregoing stipulation is approved, and IT IS SO ORDERED.

Date: _________________

_______________________
Honorable William H. Alsup
Judge of the United States District Court

1


Dated: April 19, 2012

MORRISON & FOERSTER LLP

By: /s/ Marc David Peters

MORRISON & FOERSTER LLP
MICHAEL A. JACOBS (Bar No. 111664)
[email]
MARC DAVID PETERS (Bar No. 211725)
[email]
DANIEL P. MUINO (Bar No. 209624)
[email address telephone fax]

BOIES, SCHILLER & FLEXNER LLP
DAVID BOIES (Admitted Pro Hac Vice)
[email address telephone fax]
STEVEN C. HOLTZMAN (Bar No. 144177)
[email address telephone fax]

ORACLE CORPORATION
DORIAN DALEY (Bar No. 129049)
[email]
DEBORAH K. MILLER (Bar No. 95527)
[email]
MATTHEW M. SARBORARIA (Bar No. 211600)
[email address telephone fax]

Attorneys for Plaintiff
ORACLE AMERICA, INC.

2


Dated: April 19, 2012

KEKER & VAN NEST LLP

By: /s/ Matthias A. Kamber

SCOTT T. WEINGAERTNER (Pro Hac Vice)
[email]
ROBERT F. PERRY
[email]
BRUCE W. BABER (Pro Hac Vice)
[email address telephone fax]

DONALD F. ZIMMER, JR. (SBN 112279)
[email]
CHERYL A. SABNIS (SBN 224323)
[email]
KING & SPALDING LLP
[address telephone fax]

GREENBERG TRAURIG, LLP
IAN C. BALLON (SBN 141819)
[email]
HEATHER MEEKER (SBN 172148)
[email address telephone fax]

KEKER & VAN NEST LLP
ROBERT A. VAN NEST (SBN 84065)
[email]
CHRISTA M. ANDERSON (SBN184325)
[email]
DANIEL PURCELL (SBN 191424)
[email address telephone fax]

Attorneys for Defendant
GOOGLE INC.

3


ATTESTATION

I, Marc David Peters, am the ECF User whose ID and password are being used to file this STIPULATION AND [PROPOSED] ORDER REGARDING SELECTION, ARRANGEMENT AND STRUCTURE. In compliance with General Order 45, X.B., I hereby attest that Matthias A. Kamber has concurred in this filing.

Date: April 19, 2012

/s/ Marc David Peters

4



  


Oracle v. Google - Day 4 Filings; Why Are APIs Hard to Develop? ~mw | 178 comments | Create New Account
Comments belong to whoever posts them. Please notify us of inappropriate comments.
Why Are APIs Hard to Develop?
Authored by: awkScooby on Friday, April 20 2012 @ 10:23 AM EDT
APIs are easy to develop. Every CS101 student in the world can churn out an API. It's good APIs that are hard to develop. They require being good at abstraction. One software engineering book broke developers down into two types: abstractionists and implementationists. It suggested that only about 10% of people are good at abstraction, which is why so many designs by committee end up being so bad -- 90% of the people that aren't good at it end up overruling the 10% who are.

You generally have one shot at an API -- once it's released and people are using it, you can't change the rules without breaking the code everyone has already developed.

[ Reply to This | # ]

APIs are hard to develop because you are thinking of so many things at once
Authored by: Anonymous on Friday, April 20 2012 @ 10:23 AM EDT
APIs are hard to develop because you are doing so many things at once. You are
not just thinking about the 'words', the non-functional elements (that which we
call the interface, and which most people would agree is unprotected). But you
are simultaneously thinking about how you would implement the functionality. You
don't like to introduce new words that cannot actually be used because nobody is
creative enough to express them in a way to make them do something interesting.
And you are also thinking about all the interactions others will do with the
interfaces once you provide an implementation for them.

The plain 'interface' part of the API is super simple. All it takes is come up
with a new non-existing word in the language (package/class/method name plus
signature) (it would be nice if they 'sounded' somewhat interesting, but in
theory it could be random letters). That is why that is unprotected.

The creative hard part is giving a description (the implementation) of the new
word. And thinking about all the interconnections that others will do with it
using the new word in sentences that describe new ideas using both the old
existing and new words you came up with.

The selection, arrangement and structure of the new API kind of falls out of all
that. It is what is left behind if you only look at the functional requirements
(the new constants introduced) taking into account all the creative elements.

So it is both super hard (imagining all the possible uses of the new API) and
super easy (writing down the selection, arrangement and structure of the new
interface that just falls out of the functional requirements you thought up).

[ Reply to This | # ]

Corrections Thread
Authored by: bugstomper on Friday, April 20 2012 @ 10:40 AM EDT
Please summarize error->correction or s/error/correction/ in the Title box

[ Reply to This | # ]

Off Topic threads
Authored by: bugstomper on Friday, April 20 2012 @ 10:41 AM EDT
Please stay off topic here

[ Reply to This | # ]

News Picks Thread
Authored by: bugstomper on Friday, April 20 2012 @ 10:42 AM EDT
Pick your News here. Please put the title of the News Pick in the Title box and
include a clicky link to the article for when it scrolls off the sidebar.

[ Reply to This | # ]

Comes transcripts here
Authored by: bugstomper on Friday, April 20 2012 @ 10:43 AM EDT
Please post your transcriptions of Comes exhibits here with full HTML markup but
posted as Plain Old Text to make it easy for PJ to copy and paste.

[ Reply to This | # ]

Functional Relationships: Not really relevant.
Authored by: Anonymous on Friday, April 20 2012 @ 10:45 AM EDT
You see (Or maybe I see, IMHO 'n all dat), all of that is just implementation.
As an example, If implementing the max() function, most would create and use a
greater-than function(or operator) first, and use that. That creates a
relationship, but it is in the implementation, not the API.

As I see it, there are three steps.
1. Create a list of all the things that a developer needs.
2. Give them names, argument lists and return types.
3. Arrange them into classes, separate libraries etc. so that the developers can
find them where they expect them.

It is step 1 and 3 that seem to be hard, if only going by the number of
libraries that get it wrong. The choices made can reflect the intricacies of the
implementation, but that is usually the sign of a bad API. Libraries whose APIs
are too closely linked to how they are implemented tend to make assumptions
about how they are called, and fail when a programmer uses them creatively.

From an outside standpoint, the API is just how to access the library. It is
best if the API is designed before the library, but many times it is somewhat of
an afterthought. And we suffer!

[ Reply to This | # ]

Suppose the API's are copyrightable
Authored by: vadim on Friday, April 20 2012 @ 10:45 AM EDT
Let's just suppose the API's are copyrightable.
The following question is: What is the license which governs
the java Api?
Sun released Java under GPL so API's are also under GPL...
So if Google relicense their implementation under GPL they
will be OK?
Seems like Oracle figthing to protect and promote GPL.... :):)

[ Reply to This | # ]

APIs are hard just like ERP is hard
Authored by: artp on Friday, April 20 2012 @ 11:26 AM EDT
Well, neither one NEEDS to be hard. But most processes are
just not obvious without some digging. Many things happen
without being documented. Relationships spring up to meet
new and unanticipated needs. Business changes, and the
structure and interconnectedness needs to change to match.

The big fail for business are those undocumented procedures
that make someones's job possible, sometimes a critical
someone. This is always because the last great, new project-
to-meet-all-needs didn't account for that business
function. If the new project doesn't find those procedures,
then it will fail.

ERP projects usually fail because they are looked at as IT
projects, when in reality they are business projects. This
is because the business has the largest effort required to
make the project successful. They need to define how they do
business. When I have seen ERP projects done as an IT
project, the rules always turn out wrong, and the project
fails, or is relegated to some dark corner where it isn't in
the way.

APIs are similar in that the way the structure is initially
defined really needs to match how the programmers work, and
what projects are attempted using those APIs. The
definitions really need to match reality. Otherwise, the
APIs will fail, or be relegated to a dark corner, where they
are not in the way. Workarounds will abound, and there will
be much wasted effort.

---
Userfriendly on WGA server outage:
When you're chained to an oar you don't think you should go down when the galley
sinks ?

[ Reply to This | # ]

Why Are APIs Hard to Develop?
Authored by: Anonymous on Friday, April 20 2012 @ 11:38 AM EDT
_GOOD_ API's are hard for several reasons:

- A useful API has to address the problem at an
appropriately useful size. Let's take dates as an example -
if we make an API to help developers work with dates we
could choose to deal in dates according to the Western
calendar. Or we could choose some other date system - for
instance based on the Hebrew Calendar. Or we could have
both, with translations available. But then what about other
calendar systems? There are lots, both historic and
current. Like the Persian Civil Calendar. Which has been
altered repeatedly. So we'd have to know which version of
the calendar was being used. The choices we make here are
dependent upon what the aim of the API is. If it were to
deal with historic events, then we might need a variety of
defunct calendar systems included. But if it's only going to
be used in Western countries, then ISO8601 might do. Except
it will be in use in the US & Europe, so we need date
formatting which is appropriate to locale... Hopefully you
will have seen that defining the scope and size is as much
about excluding as including.

The point is that the job of deciding on the problem you
want to help with can require many decisions. And if you
make a wrong choice, then the API becomes far less useful.

- Figuring out what operations the API should encompass is
hard too. It takes lots of thought, experience, talking to
potential users of the API, testing and iteration to get it
right. Too small a set of operations makes the API not
useful, and too large a set makes it unwieldy. For instance,
carrying on with dates - one of the operations people want
to do on dates is to add a number of days. But what if you
want to add a month? If the date is the 6th April, then most
people will think that adding a month should give 6th May.
But what if the date is 31st August? 30th September or 1st
October, or return an error, or make it dependent on a user
setting? Does all the above hold for leap years, and leap
days? And subtracting months is even more complicated.
Working out a convenient, useful set of operations and the
abstractions to describe them can be hard. IMO there's an
element of creativity involved in the solutions
you choose, like there is in making cake.

- Naming does make a difference. The names that you choose
for things matter. Short names are better for typing. Long
names are often more descriptive. Consistency is
important too - you want people to be able to predict the
name you will have used without having to resort to
documentation. The structure of names can help with
consistency - if the names follow rules. For instance
ObjectVerb or similar. And of course the meaning in the
names is a help - you could call a function NextDay or
TheDayAfterToday or FollowingDay or Tomorrow or DayPlusOne
or Arnold. Notice how Arnold can mean what I want it to
mean, but it doesn't convey it because you don't associate
Arnold with anything in this context. Worse, I could name
things badly - what if TheDayAfterToday does not return the
date tomorrow?

- Next comes the job of tying everything together. This is
mechanics - it's hard, but it's where being methodical helps
hugely; it's silly to use date in one format everywhere
except in one function where it's in another format for no
good reason. It's not sensible to leave out a crucial piece
when it's needed to tie two parts of the API together. It's
sensible to give users of the API some foundation before
attempting the more esoteric functions. So probably
AddToDate comes before the ThisDayInHistory function. So
sensible ordering can help or hinder, but it's not a
creative act - it's the product of some logic, some random
choice, and some design choices earlier. For instance, it's
not terribly sensible to group dates with chairs. Instead
you'd probably separate them into two bits of code - things
to do with chairs don't belong with things to do with dates.
But things to do with age might be with dates. Or they might
be separate; it's a choice that depends on mood as well as
the aim of the API.

- And then there's implementation, which the Oracle team
seem to be trying to blur as much as they can into the API
design. That can be another huge job. Or a small job. It's
also creative, in that there are more than one way to make a
cake; you don't have to use cane sugar - and using treacle
might make the cake more interesting, or you might change
the order of adding ingredients.

I've given these as discrete activities, but often it's a
mix - for instance, some implementation while figuring out
the shape things should take through experimentation and
iteration.

[ Reply to This | # ]

Simple. APIs are NOT hard to develop.
Authored by: celtic_hackr on Friday, April 20 2012 @ 11:47 AM EDT
Well not hard to develop, unless you don't know how, or weren't educated how to
write software.

There is a big difference in developing a decent API and writing decent API
code.

Let's step back and go back to basics.

def: API (n) An application programming interface. An application programming
interface is the name of the thing you wish to execute, and any values (i.e.
parameters) that it requires to respond with an answer. An application
programming interface must also include: the type (see type) of value of each
required value, the order in which the values must be arranged, and the type of
value the API returns, if any.

def: type (n) A type is a particular form of information used by a computer to
return an answer to a question. Types can be simple things like: an integer, a
floating point number, a character, a string of characters, or an array of
integers. A type can be something complex, like a class of animals.

def: class (n) The structure, characteristics, components, procedures and
functions which describe a real or imaginary object.

For example of a complex API. Following types are in all Upper case (contrary to
standard programming standards).

API: function ANIMAL WhatAmI ( ANIMAL_ATTRIBUTE() attribs, ANIMAL_HABITAT()
livesin, ANIMAL_BEHAVIOR actslike)

Here we have three complex "types". Each of which is in itself an API.
At least one of which is a "class", ANIMALS.
The other three could possibly be simple arrays of lists. As you can see, I've
include "()" for some of the type, creating an "on-the-fly"
new type. The "()" indicating I've made an array type of the relevant
base type.

ANIMAL_HABITAT would be most easily implemented as an array of strings.
ANIMAL_ATTRIBUTE would require at the least a key-value pair (has_legs :
[True/False], legs : [integer], etc), and would likely be best implemented as a
"class". ANIMAL_BEHAVIOR might be harder to categorize, depending on
how it is to be implemented. It could be a simple list of strings, but could
also be a collection of lists of strings, and methods. Of course my three
parameter types would be contained within my ANIMAL class. They could also be
grouped into one single type, thus reducing the need to pass three parameters.
There are many option to create "WhatAmI" API. But once an API is
created, everyone who wishes to make something compatible HAS to implement the
"API" in the same way. And in case you haven't figure it out my API is
"20 questions" implementation, which takes clues for input and return
the identity of a specific animal as output. There is nothing in my API which
appears to limit the clues to 20, but the underlaying code just might. It depend
on how I choose to implement it. Will I allow cheaters? Or enforce a morality?
Or enforce a morality for all implementations, but leave an undocumented
backdoor API parameter which allows me to write cheater implementations and thus
gain a competitive advantage over my competitors?

You see the API is nothing more than the "API call" [ie the thing at
the top of my example], It is the "INTERFACE", how it is written
underneath is irrelevant. The interface is the "DOOR" you have to
knock on for an answer. An API library is merely a list of APIs. The API code
is the code or library of the IMPLEMENTATIONS of the API.

[ Reply to This | # ]

Bad Legal Question PJ
Authored by: MDT on Friday, April 20 2012 @ 11:53 AM EDT
Sorry, but it is.

It doesn't matter how difficult API's are to design. Difficulty of the work
does not make API Specifications copyrightable.

Brain surgery is unimaginably difficult, it doesn't make the patient's brain
copyrightable.

Writing 'I love you' in single atoms is unimaginably difficult, it doesn't make
the final product copyrightable.

API's may be difficult to design as a whole, but it doesn't make them
copyrightable. Anymore than you can copyright the idea the Theory of Relativity
and the mathematics that designate the relationships. All an API specification
is a set of rules on how to call the API code. The API code can be copyrighted.
Not the 'how do I access it'.

The design of your house can be copyrighted, the layout of your lawn can be
also. But not the address in the address book nor the directions on how to get
there.


---
MDT

[ Reply to This | # ]

To Be Contrary...
Authored by: sproggit on Friday, April 20 2012 @ 12:06 PM EDT
I don't accept this view, for two main reasons.

1. Oracle are twisting this to try and given the jury the [false] impression
that by implementing APIs to be compatible with Java, Google have
"taken" something of "value". This is all mis-direction, and
we should not fall into the trap.

2. It's nonsense.

Let's start with my second reason. Suppose I wanted to write a function which
took a string of text, searched it for a smaller string of text, and returned
the starting position of the first match as an integer count of characters
"in" from the first character...

Let's call this function "inString".

Rather than force developers to copy my code over and over into their software,
we'll put it in a callable method, with parameters, and let them invoke it from
an included library of code...

So... our inString function needs 2 parameters: the string we want to search,
and the pattern we want to search for. Both parameters are string fields. So
let's think about how complex the API to this function would be. Here's an
example:-

function inString(str $searchString, str $searchPattern) {
...
}

And that's it. The economy and simplicity of this API is achieved by
understanding what parameters we need in order to perform the intended
computation, and then ensuring that we ask for them in a logical way.

The *hard* part is writing the logic that sits within the method. In other
words, what program instructions are we going to use to tell the computer how to
step through our search-able target, looking for the pattern? That's quite a bit
more difficult that defining the API.

Notwithstanding the fact that some method calls get a little bit more complex
[for example with discretionary fields, with parameters that are themselves
objects, etc, etc] this is as hard as it gets.


OK, now that we've argued [if not established] that defining the interface to a
*method* is actually not that hard, let's think about collecting those methods
together into groups that make it easier for programmers to work with. In order
to do that, let's think about all the different data types and processing
activities that a typical computer language might be expected to handle...

Well, we could reasonably expect to find:

Strings of characters and string manipulation activities...
Math functions, perhaps split into integer and real numbers...
Input and output processing (reading from an input stream, etc)...
Perhaps there might be extensions for things like database processing...

So lets imagine that we've got a collection of methods:-

sqrt() - a Square Root function
strToUpper() - a function to turn a string into upper case
println() - a function to print anything to the selected output device
mod() - a function to produce a modulus of a number given a divisor for it
and so on...

If we look at our collection of methods, we will quickly realise that, hey... we
have a number of functions and methods that relate to maths processing. Some of
these are integer math, some real number math, and so on. We also have a stack
of functions for manipulating strings.

Now, because we want to make life easy for our developers who will use this
language, we are actually going to group "like" methods together. So
we will put all the math functions together, and all the string functions
together, and so on.

Guess what?

Now we have a fairly complex API. We have defined the *interface*. We haven't
written a single line of logical processing code. We have just written the
interface definitions by which application programs can call our libraries. We
have organized our functional components into sensibly arranged groups and named
them accordingly.

This is *exactly* what Sun did with JAVA. It is also *exactly* what is done with
pretty much any Object Oriented language you care to mention.... In short, JAVA
has done *nothing* that is unique, special or innovative. In grouping the
various parts of JAVA, they have done something sensible.

For those of you who are familiar with Eric Raymond, author of "The
Cathedral and the Bazaar", you may have come across his "other"
book, "The Art of Unix Programming". In there, he sets out a series of
rules, "maxims" for writing good code. I do hope he will forgive me
for quoting them here, but they are so totally and utterly relevant to this
debate, here we go:-

1. Rule of Modularity: write simple parts connected by clean interfaces.
4. Rule of Separation: separate policy from mechanism; separate interfaces from
engines.
10. Rule of Least Surprise: In interface design, always do the least surprising
thing.

There are 17 rules in total, and I encourage anyone who would like to be a
better programmer, or anyone interested in programming, to go buy a copy now. [
You can actually read the book on line - but give something back, hey? ]

The point is - these rules are terrifically important to the overall concept of
programming. The writers of JAVA knew this, as did the writers of Android. The
API - the grouping of a function name [the function being the bit of code that
does something, and has to be named so that you know what to ask the computer to
do] and the parameters it needs - is eloquently described by Mr Raymond in his
book.

There are reasons that he offers those "rules" - because thousands or
millions of programmers have learned by trial and error that this is the best
way of doing things. Why implement something which is less effective?


Oracle would have the jury believe that there is some deep mystery in having a
square root function that takes a number as an input parameter, and gives a
second number as an output. They would have you believe that putting the
"square root function" with all the other math functions (as opposed
to with the string functions) and calling this grouped library
"java.math" is somehow an act of un-bridled genius.

Well, I've got a question for them, then: if it was so incredibly clever, and if
it was an act of creative, inspirational genius, then why didn't Sun get a
patent on it? Engineers have patented particular chemical compounds, lubricants,
paints and so on. So why not this fabulous structure?

Answer: because to be awarded, a patent has to be "non-obvious to one
skilled in the art". Frankly, it is totally obvious that it's necessary to
collect and group a programming languages functions into organizations that make
it easier for developers to use. If you don't do that, no-one is going to use
your language, because it's too hard to learn...

This is utter nonsense, and it is only being put before the jury in this case
because without it, Oracle have no case.

I go back to my previous conspiracy theory, that this case is about protecting
Mr Ellison and the Oracle Board from shareholder lawsuits on the grounds that
they made a stupendously bad decision to pay $1.8 billion over-the-odds for Sun.
Mr Ellison and the Board have to give the impression that they believe that they
have something so valuable it's worth suing over, otherwise they admit that they
bought, to borrow the expression, "a pig in a poke".

Well, all I need to say to that is, "oink."

"Oink, oink!"

[ Reply to This | # ]

I feel a car analogy coming on :)
Authored by: bugstomper on Friday, April 20 2012 @ 12:32 PM EDT
I once had a Honda that had a timing belt that had to be replaced every 60,000
miles or so. If you didn't replace it before it wore out it could break while
driving at speed and potentially destroy the entire engine when it whipped
around.

The timing belt was pretty inexpensive. Replacing it was very expensive, because
to get to it involved removing a huge amount of pieces to get to it, maybe
pulling the entire engine (I'm not a mechanic so I could have details wrong).

Good API design is a matter of designing how everything goes together so you
don't have to take everything apart just to replace an otherwise cheap part. Or
so you don't need to be a contortionist with extensible hands just to reach the
spark plugs when you have to change them regularly.

Eventually Honda replaced the timing belt in the design with a timing chain that
doesn't wear out so often. And spark plugs went away so it was no longer an
issue how easy they are to access.

Good API design is a matter of figuring out how to make working with the API
easy. In Java that is not just a matter of making it intuitive for programmers
who need to call the libraries, but also easy for programmers who need to use
the API by implementing interfaces and extending classes.

[ Reply to This | # ]

Another aspect to Java APIs
Authored by: bugstomper on Friday, April 20 2012 @ 12:42 PM EDT
I mentioned this at the end of my last comment, but I thought I would give it
its own topic.

I haven't seen mention of one aspect of Java API design in particular.

A Java library (and its API) are not just designed to be called by the
application programmer. The API may include interfaces and abstract classes that
are used by being implemented. Also some of the classes may be used by being
extended by the application programmer.

Making it easy to extend a library in these ways is part of good API design. You
have to consider what elements of the library classes should be exposed as
public or protected and what can be kept private. There is the notion of how to
design the API so that the result is not brittle (which means that any changes
are likely to break other changes).

[ Reply to This | # ]

API's are not a-priori difficult to develop.
Authored by: BitOBear on Friday, April 20 2012 @ 01:22 PM EDT
Saying API's are difficult to develop is like saying it is difficult to pour
concrete or write an article or paint.

Some API's must be labored over and some flow naturally.

Writing a good API "for the ages" can be tricky if the thing you want
to interface with is tricky. But they can also be a breeze to write if the thing
you want to interface with is very straight forward.

Sometimes there are a lot of words that say very little, some times there are
very fiew words that say a whole lot each.

I'll go back to pouring a slab. You dig a hole. You mix concrete. You pour
concrete into the hole. Then you smooth with float. What could be easier...? Of
course there is some heavy lifting which is one kind of "hard" and
then you can end up like my neighbor. He hired day laborers and didn't do the
planning right and his slab ended up "good" but too close to a
building that was not to code so it took him like three years to go back and get
the permits he should have had and then get the building built because his
foundation was wrong.

So the real statement is that its easy to write an API and its -really- easy to
make a terrible and useless API. On the other hand if you learn the rules and
check your work, its is not hard to write a decent or even good API.

There are a gifted few from whom salient and magically good code flow like water
from a river. For these people, the skills that make their code good makes their
APIs good. This is because their code is good so it is "hard" to
misuse the thing being interfaced with.

The reason many systems are broken-down into or provide multiple APIs is that,
like with anything, a larger number of smaller, more well-defined things are
easier to create and deal with than one large complicated thing.

It can be Herculean to write a good interface to/for a bad or complicated
library. More-so, if you try to write an "adapter" library that can
work in more than one context (like the way the Qt library can be used over both
Windows and Xorg-on-GNU/Linux). But such adapter libraries and their APIs are
vital to making things generally work.

So the difficulty is naturally proportional to the task. We just forget about
the easy ones and tell the war stories about the hard ones over and over again.

[ Reply to This | # ]

User Interface
Authored by: Anonymous on Friday, April 20 2012 @ 01:50 PM EDT

The API is the User Interface for the library (the Java standard class library in this case). The user in this case are the application programmers that wish to use the functionality exposed through the interface by the library.

I believe that developing a good UI (or API) is a creative process where you have to make trade offs to satisfy many different constraints: It has to be easy to use the right way, difficult to use the wrong way, possible to implement the library exposing the interface efficiently, easy to use the interface efficiently, and generally things needs to be where the users expect them to be, and so on. Some designs make some styles of programming possible or easy, and make other styles hard. You have to imagine how the users will want to use the functionality. As with other UIs there are often many ways to do it and exposing the underlying implementation to directly is seldom a good idea.

Look at e.g. the Java, .Net, Python, and c++ class libraries to similarities and differences. They are clearly inspired by each other, but there are also differing choices.

But in this case, I do not believe, Google has claimed that they have created a new language. Instead they have openly used the Java language (design, not implementation). And I would think, that a Java-programmer would expect to be able to use common functions like Math.sin() if they where told that they could use the java language in Googles new implementation. In most users mind (and I believe in Suns marketing) the standard library is part of the language (why else would the library implementation be tested as part of the java implementation certification).

[ Reply to This | # ]

Registration does strengthen one's copyright
Authored by: Anonymous on Friday, April 20 2012 @ 02:36 PM EDT
I really would like to think that Mr. Jacobs knows a bit more about copyright law than this. For example, your copyright arises when your work is embodied in a tangible medium of expression, i.e., you write it down or enter it into a computer. You don't have to file anything with the Copyright Office. If you want to sue someone for infringement, then the work in which you already claim a copyright needs to be registered with the Copyright Office.
There are several ways that one's copyrights are strengthened by registration with the Copyright Office. Registration three months after creation or before infringement occurs permits statutory damages and attorneys' fees to be awarded. Registration of one's copyrights is also a necessary step if one wishes to prevent importation of infringing works through U.S. Customs.

Registration may not trigger copyright protection, nor extend coverage to what otherwise would not be protected, but it does strengthen copyright and thus Mr Jacobs statement seems reasonably accurate and justified.

[ Reply to This | # ]

Another shot at defining "Interface" and friends.
Authored by: BitOBear on Friday, April 20 2012 @ 02:38 PM EDT
So I have been looking for a way to make this whole thing more concrete to a
less technical audience. Here is another go at that.

Each of us is familiar with at least one (computer) User Interface. We click our
mouse and push our keys and look at the screen. We learn the basics of how to
start and use programs as a factual issue where we click the start button then
go through the menus and finally click the (picture of) the program we want to
run.

But we have learned what -seems- to us to be the unwritten rules of the
interface. Things like, if you are going through the start menu dance and you
move the mouse too far away or click on something outside the start menu tree,
the start menu closes and you have to start over.

So the User Interface is the combination of concrete things (buttons and menus
and whatnot) and the "rules of the road" for using those things that
end with more or less desirable outcomes.

BUT...(sadly) we also know that sometimes while we are doing things the machine
seems to decide to go off an do something else. Like if you start up a MS
Windows machine and try to open your programs before the system is really ready,
well the start menu will disappear on you before you can click on the (picture
of) the program you want to start.

We also know, if we have ever seen a pop-up window while browsing the web, that
sometimes programs or windows show up when we do not want them too.

And sometimes something "grabs" the mouse and you cannot do anything
other than deal with that something until it is satisfied and lets go of the
mouse.

Why is this?

Well the user is using the screen, but the user is not the -only- thing using
the screen. The programs are using the screen as well.

The screen has a consistent set of rules. These are things like "when a new
top level window opens the start menu tree shall be closed". This is a fact
of how the screen works and not a deliberate act on the part of the user(s).

So the truth behind the smoke is that the screen, as a usable thing, has a whole
interface. Part of that interface is pointed at you, the user, and most of that
interface is semantic because you, the user, have learned what to do when you
see a bunch of buttons or check-boxes as opposed to menus.

So the running programs are other "useers" of the screen. But those
programs cannot "learn" the feel of things and they cannot "just
look at" the screen.

So the programs (the "application programs" he said grinning) have
their own interface to the screen which is all about seeing concrete things.
This interface may have interrogatories like GetWindowList(), who's job is to
gather up a list of the windows, and it may have imperatives like
MoveWindowToTopOfWindowStack(target_window). [The latter doing for the program,
the same thing you do when you click the exposed part of a mostly-hidden window
to get it to be "The one on top".]

These imperatives have all the same side effects when the programs do it as the
actions of a user when they do it with the mouse. In fact, the mouse machinery
typically invokes the imperatives on your behalf through the very same calls.
The reason that the start menu tree goes away is one of the logical rules built
into the screen. As such it is implicitly part of the User Interface, and
explicitly part of a well written set of instructions that accompany the
Application Program Interface.

SO... my parenthetical about Application Program Interface where I made it seem
like the name API is all about the fact that "an application program"
is using the interface is not a deliberate truth, its just a good analogy of the
moment.

The real thing about the A(whatever)I interfaces is that these are the
"truths" of the interface as seen from inside a concrete expression of
code. They are the rules and imperatives and interrogatories associated with the
interface.

When a programmer uses these A(whatever)I's he -always- uses the "API"
in his source code. This is why we talk about "API files". Compilers
don't process "ideas" they process concrete details. We collect those
concrete, computer useful parts into files. It's just that simple.

Now Sun's "write once, run anywhere" where "anywhere", we
now know, is defined as "anywhere that happens to be running an instance of
the same, or later, version of the particular platform (ME, SE, etc) as the
program was written and compiled for".

This "WORA" is achieved because when a given compiler is applied to a
given file it -must- produce the same code every time. Well, it "must"
-IF- it expects that code to "match up to" something that already
exists. Something like, say, a library that was also compiled with that compiler
and file.

This post compilation expression of the API is the ABI, or Application Binary
Interface. Without the ABI, one would have to re-compile the library every time
one compiled the program, and that would be painful (and it would also require
that people like Sun deliver the full source code to every user, which goes
against the whole "secret" part of offering proprietary software).

So there is a thing. And that thing offers "an interface" and that
interface my be offered to people (users) or programs (applications) or both.
The interface offered to a user can be -must- -be- more touch-and-feel that the
interface as seen by other programs because programs can neither touch nor feel.
That interface consists of concrete elements and rules (including "thou
must" and "thou must not" rules, along with "by the
way" rules like how opening a window closes the start menu). The
code-focused expression of concrete element and rules is the API. The part of
that code-focused expression of the API that the compiler can read and
understand is the "API Files". The consistent re-expression of the API
by the compiler into the compiled result, including the rules governing that
re-expression is the ABI.

Any given pile of code that has concrete elements -could- define an API if those
concrete elements can be found/seen from outside the compiled result. The set of
all "visible" elements -does- create an API whether you want it to or
not (a reverse-engineer can poke at your concrete elements and figure out how to
invoke them and intuit rules of good and bad practice regardless of your
intent). This is the "defacto API" of a body of code.

A "formal API" is a deliberate condensation and expression of the
parts of a defacto API that the builder of a thing makes available to the
expected audience of programmers.

A given element of a formal API may occur/appear in more than one formal API.
For instance a library contains one defacto API, and the programmer may disclose
three formal APIs for using that library. The library may need to have one call
made before it can be used at all, say "StartLibrary()".
StartLibrary() would then be a significant and vital part of all three disclosed
formal APIs.

If a programmer decided to use such a library he may decide that his program
must use more than one of the disclosed formal APIs. He then must examine them
and "discover" that StartLibrary() must be called for both but it
should not be called twice. The programmer is now venturing into the defacto API
since he is doing a mash-up of the formal APIs.

The programmer may even discover that the three disclosed formal APIs have
mutually exclusive function. For instance it may be a case that of the three
formal APIs, no more than two can be used in any one program because of some
design element or quirk. Now the programmer is -deep- into the defacto API.

It might even be discovered that the formal APIs do not play well together even
though they are supposed to be fine working together. This is now a bug in the
defacto API that is not part of any of the formal APIs individually.

A API may be written as one formal API with constituent sub APIs which then
cause more than one library to be brought in by the compiler. This can happen
because the sub components are all large and the designer doesn't want to flood
the computer. For instance I might offer up an image API that has
load-from-file, display-on-screen and send-to-printer rendering calls. These
three sub-sections might be in different libraries so that the photo editing
application doesn't need to bring in the printing stuff until/unless it decides
to print.

And so on...

So there is a real interface in full. The interface as seen by the programmer.
The interface as seen by the compiler. And the interface as seen by the user.

Skilled professionals in the art are used to this entire thing, but may draw the
lines between formal and defacto in different places. They may consider a
library to have one API comprised of all the formal APIs or they may consider it
to have many separate ones. The choice of where and how to separate things and
disclose things is a -purely- -stylistic- decision at the formal level. And the
programmer who ends up using the formal API(s) may decide to treat them as if
they were a different number of API(s) as suits his view of what needs to be
done.

So, ta da! Thats why the only word that means anything is "interface"
and the idea of interfaces AP or otherwise, is not concrete.

[ Reply to This | # ]

My thought on API developers saying that writing APIs is a difficult thing.
Authored by: s65_sean on Friday, April 20 2012 @ 02:46 PM EDT
Take anyone with a fairly technical job and put them under oath in a witness box
in a courtroom, and then ask them if what they do for a living is important and
difficult. What do you expect the majority of them would answer? Why
"Yes" of course. They need to justify their existence and high salary.

[ Reply to This | # ]

Oracle v. Google - Day 4 Filings; Why Are APIs Hard to Develop?
Authored by: jvillain on Friday, April 20 2012 @ 02:55 PM EDT
Even as a programmer I have seen enough smoke blown over the last week to make
my head hurt. I can't imagine how the judge and jury must be feeling. But the
judge is showing frustration. So here are two questions I have.

Who actually coined the phrase "Application Programming Interface" and
how did they define it?

Second if the judge decides that he isn't going to get a straight answer from
either side can he call a friend of the court to weigh in?

[ Reply to This | # ]

Anti compatative behavior
Authored by: Anonymous on Friday, April 20 2012 @ 03:38 PM EDT
The I in API stands for interface.
If I am rigth companies have lost lawsuits because they didn't open up their
interface specifications so that others could make their own programs/equipment,
which were ment to interact with the other equipment through it's interface. So
my question is, can the actions of Oracle to limit the use of their Java API's
be considered as anti compatative behavior, especially since they have a
monopoly on Java ?

[ Reply to This | # ]

Oracle v. Google - Day 4 Filings; Why Are APIs Hard to Develop?
Authored by: Marc Mengel on Friday, April 20 2012 @ 06:12 PM EDT
It's a mis-labelling issue. Good code libraries are hard to design and develop. Having developed the design for a good code library, the API is simply the listing of the names of the external library entries and their parameters. They are trying to say that designing the library is "designing an API".

But that's just silly.

The API is like the little picture of the dashboard in your car owners manual, with the arrows saying "radio volume button" and "headlight switch". They're saying that it's really hard to make such a diagram because first you have to design the car...

[ Reply to This | # ]

The API (list)
Authored by: jpvlsmv on Friday, April 20 2012 @ 08:49 PM EDT
So we have as "facts" in the case:

a) The APIs as a whole meet the minimum creativity requirement to be protected
by copyright.

b) individual elements of the API -- the file, class, and method names are not
protected.

c) The 37 Android APIs are substantially similar to the 37 APIs from Java.

So the question is, can a superset of the whole list (the Android APIs as a
whole), which is made up of a different selection of unprotectable elements,
infringe the copyright of the whole list because they overlap with a subset of
the original one?

Feist v. Rural established that a telephone book as a whole could be protected
by copyright (meaning that you couldn't just photocopy the whole book), while
still allowing the selection and arrangement of subsets of that data to be
freely made. Even though Feist had used the copyrighted phonebook as its source
material, their phonebook was found to NOT be an infringement of Rural's
copyright.

Just like Rural, Oracle refused to license its list to Google, and Google
created a different list for its needs.

--Joe

[ Reply to This | # ]

They are not
Authored by: Anonymous on Friday, April 20 2012 @ 10:59 PM EDT
He is lying to try and convince the jury that Oracle deserves a lot of money.

API is technobabble for the collection of subroutines that are contained in a
library. Usually they are collected into groups by function, or some similar
catagorization.

Most APIs are barely designed at all. The programmer thinks of a few things she
needs and adds to it as time goes on. Useful functions are kept, less useful
ones are taken out.

It is possible to sit down and carefully design a set of subroutines for a
library. This is no different than the work of deciding how to divide up the
work in any program. Well designed libraries definitely owe their good design
to the experience, intelligence, and thoughtfulness of their author, but this is
not different than the normal day to day work of a programmer.

[ Reply to This | # ]

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 )