5 ms·

How to Design a Good API and Why It Matters (2007) [video]

52 points by fagnerbrack 9y ago

deleted 9y ago
[deleted]
seanmcdirmid 9y ago
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 9y ago
  I thought .NET isn't that bad especially with LINQ. In what way is Java better?
  - pjmlp 9y ago
    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 9y ago
      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 9y ago
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 9y ago
  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 9y ago
    > 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 9y ago
      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 9y ago
        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".
anonymousDan 9y ago
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.

52 points by fagnerbrack 9y ago

deleted 9y ago

[deleted]

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 9y ago
I thought .NET isn't that bad especially with LINQ. In what way is Java better?
- pjmlp 9y ago
  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 9y ago
    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 9y ago

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 9y ago
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 9y ago
  > 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 9y ago
    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 9y ago
      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".

anonymousDan 9y ago

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.