[prog] APIs for dummies?

[Dan Richter]

Ah, heck, I'll jump in too.

As the programmer of the system, you know how it works in great detail, and 
that's both good and bad. It's good because you have to know how it works 
in order to write the APIs. It's bad because you might structure the APIs 
around the way the program works rather than around what the user will want 
to accomplish.

Think about what the user is going to do. Write a few simple programs using 
the API (you'll want to do that anyway to test). If you see that the same 
five or ten lines of code are often used together, try to write a function 
in the API to replace them.

For example, in many high-level languages you can open a socket (Internet) 
connection using either the hostname or the IP address: the same function 
takes either one. From an internal perspective, using a hostname is more 
difficult because the hostname has to be resolved to an IP address and then 
the IP address is used for the connection. So if you're thinking about the 
internal workings you might force the user to resolve the hostname, then 
give you the IP address. But why force the user to do this? Do it 
internally to save the user the trouble.

If a parameter takes a default value, make it the one the user will most 
often want, not the one that's easiest to implement. For example, when 
initializing a graphics display you often have to choose a resolution. If 
the resolution parameter can be omitted, don't make it default to some 
universally available lowest common denominator (the easiest to program), 
but rather to the highest available resolution, since that's what the user 
will usually want.

All of this seems like common sense, but I promise you that many 
programmers don't apply it. Being an author of the software causes you to 
think about it in a certain way, but to write good APIs you have to think 
like the person that will use them. In fact, I recommend that you find 
someone who's not involved in the project and have that person help you 
plan the API from the beginning (not the implementation of course, just the 
design).

Put time and effort into creating the API now so that you won't have to put 
time and effort into using the API later.

-- 
   BOOT MAGAZINE: Do you consider yourself a celebrity?
   LINUS TORVALDS: Sometimes. ... But at the same time I don't have
         young girls coming and screaming at me and throwing their
         underwear! Which is just as well, as I'm a married man!