He explains that API design is very similar to language design, and I immediately thought that this particularly holds for APIs which are designed as domain-specific languages, which is one of Ruby’s strengths (read this article from Oreillynet.com to learn more about DSLs).

A few slides later he talks about characteristics of good APIs:

• Easy to learn
• Easy to use, even without documentation
• Hard to misuse
• Easy to read and maintain code that uses it
• Sufficiently powerful to satisfy requirements
• Easy to evolve
• Appropriate to audience

To achieve all these properties for an API is certainly non-trivial, but at least some of them get easier if you design APIs as a domain-specific languages: As the term says, a DSL provides a language that is tailored for a particular domain, in addition DSLs are generally declarative and hide language aspects that are irrelevant. Such a language is obviously easier to learn, use and to read than a mere API, and is more appropriate to its audience. In the end, these are known strengths of declarative languages. Here’s an example taken from the Capistrano manual (Capistrano is a Ruby DSL for remote software deployment):
[ruby]
desc “Start the spinner daemon”
task :spinner, :roles => :app do
run “#{current_path}/script/spin”
end

desc “Used only for deploying when the spinner isn’t running”
task :cold_deploy do
transaction do
update_code
symlink
end

spinner
end
[/ruby]
Though this doesn’t hide imperative aspects completely, I think it’s a good example of how a DSL feels – just as if it wasn’t Ruby but a different language.

So, is it safe to conclude that DSLs are the better APIs?

If you are starting to design a new programming language, start thinking of language identity. I do not know whether this term existed prior to this posting, but language identity is for programming languages what corporate identity is for enterprises. Of course, the scope of the language and all the nifty little features and whether it is compiled or interpreted and for which platforms the language is available is of some importance – but to make your language known, you need a lot more sexiness. This language sexiness is made by (but necessarily limited to):

• A logo. Or better, an allegory. As we see in successful languages, this does not have to be an animal (although this helps a lot with O’Reilly). Java has the coffee, Python has the snake (although the name comes from the British comedy group), Ruby has the gem.
• The name. C++ is a notable exception, taking its fame mostly from its predecessor C, which did not need a fancy name because it was the programming language sent to us from above in the Old and the New Testament. But most popular languages have names which are good to remember. Ask five developers how they are pronouncing “C#” and you will get six different answers.
• A web site. This serves as a hub for everything about your language. The Python page, for example, is so resourceful that keeping a local documentation for the language should never be necessary. There is even a Firefox sidebar for easy access to all the information on the pages.
• A figure head. At best, someone as strange and bearded as Larry Wall (PERL), at least some guru whose name is not even mentioned in full (like DHH instead of David Heinemeier Hansson, Rails/Ruby), or only by first name (“Bjarne said …”).

The essence of the humane interface is to find out what people want to do and design the interface so that it’s really easy to do the common case.

For example, Ruby’s arrays have convenience methods such as first, last, flatten, etc. which tend to be omitted in minimalist interfaces, because they can easily be implemented by clients. And Ruby also aliases method names, i.e. using multiple names for the same functionality, such as length and size of arrays. As an example for a minimalist interface, Fowler mentions the Java API for collections.

I wonder where Python falls in this spectrum. The Python folks state explicitly that

There should be one — and preferably only one — obvious way to do it.

Which sounds like a minimalist approach to me, in the meaning of “reduce stuff to the things that are canonically necessary”. But if you look at the APIs, you’ll find aliases there as well. I don’t know Python terribly well, so perhaps some Python guru can enlighten me on this?

Wrapping things up I don’t think that one approach – humane or minimalist – is necessarily better than the other. Both have their benefits and drawbacks, but like Martin Fowler I prefer humane interfaces.

Via One Man Hacking