The Artima Developer Community
Sponsored Link

Design Principles and XOM
A Conversation with Elliotte Rusty Harold, Part V
by Bill Venners
July 28, 2003

<<  Page 3 of 3


APIs are Designed by Experts for Non-Experts

Bill Venners: You listed some principles of API design in your talk. I'd like to walk through them and get your comments. You said, "APIs are designed by experts for non-experts."

Elliotte Rusty Harold: Yes. When you use an API, you are relying on the API to be correct. You assume that the developers who wrote that API knew what they were doing. For example, when you use a socket API—whether it is Winsock, the sockets API in UNIX, or—you assume that the people who designed it knew what the IP header format was, knew what the difference between TCP and IP was, knew how to route packets, knew how to talk DNS, etc., so you don't have to. You are relying on their abilities. That means they better have had some pretty strong abilities. And for networking APIs, they had better be experts in networking.

For an XML API, they had better be experts in XML. I've seen a few too many programmers decide they are going to learn XML by writing an XML API. They tend to end up making novice mistakes, and then propagating those to others. XML is imperfect. XML is confusing. It is understandable that mistakes will be made, but they are still mistakes. For example, one common mistake is confusing the XML declaration with a processing instruction. I've seen that happen at least twice in two different APIs. I made that mistake in my first book on XML. It is a very common mistake to make, but if you're at the level where you're making that mistake, you shouldn't be designing an API for other people to use.

Bill Venners: But there are two sides to that. If you are an expert at something, and you're designing an API, I think the other side is: Don't assume that the user is an expert.

Elliotte Rusty Harold: Right. You do not want to require the user to know as much about XML as you do. They should be able to accomplish what they need to be able to accomplish through your API. They should not, for example, have to specially escape characters like the ampersand and the less than sign when they use them in a text node. They should just pass in a string. Your API should handle the escaping for them.

Bill Venners: So designing an API is one way to capture and provide expertise to people.

Elliotte Rusty Harold: Right. That's really the purpose of any class library. You see it in any other environment too. For example, nowadays very few people with high performance needs would use their own numerical algorithms. They would use libraries written by real professionals in the field. These are not just professional programmers, but experts in numerical algorithms, people who have carefully analyzed the edge cases, thought about issues of precision and robustness, and designed the algorithms to perform very well despite all that. The experts can simply do a much better job than the average programmer can. In any area, that's true. None of us are experts at everything. You have to specialize and say, "This is the area where I can contribute. When I move out of my field, I'm going to rely on the work of others."

Next Week

Come back Monday, August 4 for the next installment of this conversation with Elliotte Rusty Harold. If you'd like to receive a brief weekly email announcing new articles at, please subscribe to the Artima Newsletter.

Talk Back!

Have an opinion about the design principles presented in this article? Discuss this article in the News & Ideas Forum topic, Design Principles and XOM.


Elliotte Rusty Harold is author of Processing XML with Java: A Guide to SAX, DOM, JDOM, JAXP, and TrAX, which is available on at:

XOM, Elliotte Rusty Harold's XML Object Model API:

Cafe au Lait: Elliotte Rusty Harold's site of Java News and Resources:

Cafe con Leche: Elliotte Rusty Harold's site of XML News and Resources:



SAX, the Simple API for XML Processing:

DOM, the W3C's Document Object Model API:



Common API for XML Pull Parsing:


Xerces Native Interface (XNI):

TrAX (Tranformation API for XML):

Jaxen (a Java XPath engine):


<<  Page 3 of 3

Sponsored Links

Copyright © 1996-2018 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use