At a previous company, I had the pleasure of managing a couple of development groups and projects. One group consisted of four people, the other had one. My group of four was tasked with creating a printer driver, which had no API, while the group of one (is that really a group?) was writing a toolkit with an API used by many customers to create and read a very important company file format I’ll call DDT (not its real name).
DDT had been around for several years and its scope and responsibilities had grown substantially over the years. For example, while it began as a way to simply record a graphical record of one drawing, it was now being expanded to multiple drawings and meta-data about those drawings. This resulted in a significantly large amount of new code and a completely new interaction model for dealing with the new complexities.
Things didn’t start out too well in my new role. The toolkit was supposed be released in a couple of weeks. My programmer, Bob, felt that shipping a huge XML parser with his tiny toolkit wasn’t a very good idea, so he looked for an alternative. Bob was allegedly a good programmer, but was a master in his own mind. He tried his hand at writing a simple XML writer and parser, and created it in two days of solid coding. At this point, I was not reading any of his code because I didn’t understand a thing about the toolkit yet and this was not common practice at the company either. There were no performance measurements set up for the toolkit, so there was no measurement of the new XML code either. A year later, one of my other programmers investigated why the toolkit was so slow at large files and found that it was reading the XML one character at a time. Unfortunately, for 1Mb files, this is a significant chunk of time.
Meanwhile, I asked Bob if I could see the User’s Guide so I could figure out how to use the toolkit. Did I mention there was no QA on the project either? Well, there was no User’s Guide, so I decided I would write one (no documentation person either). This way I could learn to use the toolkit and give new users a shot at getting started with a clue as well. I got some sample code from Bob and began to look over the code to read a file. I asked him if he was going to create an API for users to make it easier to read the files and he sounded confused. It turns out that I was looking at the API. You know how some people who grow up driving automatic transmissions finally climb into your car with a manual transmission and say, “Wow, that’s complicated. You have to do that yourself?” This was ten times worse. Years later one of my colleagues using the same toolkit said, “It’s not really an API if you’d have an easier time just writing the code yourself.
Keeping that thought in mind, here are some basic rules for API development.
- If you can provide the information for the user, don’t make the user provide it to you. For example, you had to set up a time structure for the toolkit to tell you what time the file was created. This had to be done even if you didn’t care what time the file was created. Instead, provide a function or method for the user to retrieve the time.
- If every user needs to perform the same set of setup steps, try to condense the steps into one, especially if the user doesn’t get any information from the API during these steps. Also, see rule #1.
- Organize your API. If it’s a bunch of classes, use solid class designs to keep jobs related to each other. If it’s a set of functions, organize them according to jobs in your documentation – an alphabetical list may be handy for reference later, but organizing by job category will help your users learn to use the toolkit.
- Document it. If I’ve learned one thing over the years it’s that writing some documentation makes you think about your code. If you start explaining and get stuck describing why something has to be done before something, why it needs certain information, or can’t figure out why you’re just not doing for the user, then you have a shot at making the API simpler.
- Provide sample code. Like writing documentation, providing trivial and non-trivial examples are the way that most users will start their own code. They will likely start by copying your code and modifying it from there. Now, picture a thousand users doing the same thing. Are they all copying this code wondering what each line does (and understanding why they’re doing it) or is it just a blur of setup garbage that users are providing to make your toolkit happy?
- Idiot proof it. If you don’t think users will try passing NULL, or null, or nil, or 0 (zero) to your API because they don’t know how to get a handle to the frisbit of grommet of the window, they certainly will. Check all input data and provide useful feedback on it (or better still see rule #1 and don’t ask the user if it’s really not necessary.)
Nothing makes an API better than trying to explain it and use it. Have your colleagues or your most critical users look at it before you release it. Then, take their feedback to heart. You may save yourself dozens of support calls and hundreds of users from fleeing to someone else’s product whose API, toolkit, or product that they can understand.