API Design

I attended the How to Write APIs That Will Stand the Test of Time session on the last day of JavaOne 2006. The speakers were from the NetBeans team and they stated that everyone is in the API business. Today a typical application is not build but assembled with a hodgepodge of open source projects, each with its own API. Since these guys are from the NetBeans team they recommended that a application be broken down into modular chunks, a la NetBeans modules or Eclipse Plug-ins. If your application is broken down into modular chunks then each module can have a separate team, life cycle, and/or schedule. This approach require a dependency management and I feel that this advice only works if you application is complex and your development team large.

An API is used to communicate not with the machine but with people, albeit developers. We all know that an API is a contract between the service and the client. The speakers said that an API is more than a contract, it is a promise. As a developer you need to make an API, as a promise, that you can keep.

Here are some quick tips from this session. Do not expose more than you have to. Factory methods gives you more freedom, because you are not tied to a specific implementation. Avoid calling foreign code in critical sections. An API is not just a method signature, it is a contract. Design to last.

Personally, I believe that a good API is one that is not noticed, that is not intrusive, that is self descriptive,that rolls of the tongue, and doesn’t require me to remember anything useless or require me to bend backwards to use.

Technorati Tags: , , ,