devgrindthinking outside the { }

Today I stumbled upon Josh Bloch’s talk How To Design A Good API and Why it Matters at Google Tech Talks. Its loaded with profound wisdom and advice from one of the masters of API design.

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?