
How to Design a Good API and Why It Matters (2007) [video] - fagnerbrack
https://www.youtube.com/watch?v=aAb7hSCtvGw
======
anonymousDan
Another cool paper related to API design is "The Scalable Commutativity Rule:
Designing Scalable Software for Multicore Processors". Basically discusses the
impact mistakes in an API design can have on performance/scalability.

------
seanmcdirmid
I still find that the Java Collection Library is one of the best design’s out
there, collections are something that modern languages still shockingly get
wrong (e.g. .net, JavaScript). Bloch really knows what he’s talking about.

~~~
maxxxxx
I thought .NET isn't that bad especially with LINQ. In what way is Java
better?

~~~
pjmlp
For a long time, the set of collection classes, which had more variety, and
parallel programming support.

Now .NET also has TPL, immutable collections.

Also regardless of what one might think of Swing or JavaFX, at least they are
there.

On .NET side, there isn't yet a GUI framework that will work without changes
across all implementations, Xamarin might eventually be it, but only after 3.0
release.

~~~
seanmcdirmid
In .net, you have to decide what optional library you are going to use to make
up for an extremely lacking standard library. Sometimes what you need simply
isn’t easy to find and you are stuck rolling your own (e.g. head and last
operations on tree sets). The JCL is very complete in comparison.

For UI, WPF is pretty good, and .net wasn’t meant to be cross platform
anyways.

------
amelius
An API should always take a transaction object as one of its parameters. This
allows you to safely run multiple services inside a single atomic transaction.
Without this possibility, complexity inevitably ensues.

~~~
chopin
Could you give an example under which circumstances you'd want this?

The last thing I'd want to give an API is such an object in order to do
something for me (like committing).

I'd had more than one occasion where I had to pass an InputStream to an API
only to find out that it kindly closed it for me. This is unfortunate if you
want to pass a ZipInputStream: as it does not hand out separate streams for
entries, closing the stream does close the entire stream, not the entry
passed.

~~~
amelius
> The last thing I'd want to give an API is such an object in order to do
> something for me (like committing).

That's not what the transaction is supposed to be passed for. It's simply
passed as a way to ensure that state changes are atomic.

Basically, if you're using transactions inside a program, passing them between
functions, that's the same concept. Except now you're passing the transaction
to an API.

~~~
chopin
How would the API ensure this when getting passed a transaction? I fail to
understand this. A transaction has two main methods, _commit_ and _rollback_
(do I miss some?). I'd never want an API to call those. That's up to the
caller.

~~~
amelius
When you manipulate the state of something (e.g. database or memory), then in
a transactional system you have to specify in which transaction the change is
supposed to occur.

So besides commit and rollback, a transaction has a "change" method, if you'd
like to look at it that way. The change method is what makes transactions
useful.

And the API function is indeed supposed to call only "change", not "commit" or
"rollback".

~~~
chopin
[https://docs.oracle.com/javaee/6/api/javax/persistence/Entit...](https://docs.oracle.com/javaee/6/api/javax/persistence/EntityTransaction.html)
doesn't have this. Could you point to a transaction (preferably in Java) which
permits a "change"?

~~~
sk5t
I am also baffled as to what this "change" operation is meant to suggest.

Enlisting possibly-unrelated operations in a common transaction is a good tool
to have in the toolbox, although it is a tad hairy to bake that into each
method signature. Spring's TransactionTemplate presents an alternate approach.

