If you think about it abstractly enough, Lego has one of the most powerful APIs in existence (Yes, I'm really using Legos as a segway into API design...). Simple and elegant, anything with those iconic plastic nubs will connect to anything else with the same plastic nubs. The only restriction? No diagonals. Of course there's various extensions and spin-offs, but at it's core, lies a simple system of nubs and circles. This simple system allows users to manifest almost any physical construct that gravity and static-friction will allow.
I've spent the past week and a half working with a group to design the API for a energy efficient house (Solar Decathlon). Basically we had to figure out how to shuttle data between Sensors, Actuators, the back-end Database, and of course the user. I wanted our API design to be like Lego bricks. Ideally, it would be simple but powerful, just a few abstract classes and interfaces that let the user decide how to handle their data. So I went off and wrote up the divine code. Then my team informed me that my design used too much energy. Crap. A long afternoon spent at a round-table in the library found us quibbling over energy, extensibility, and a few other point-less grains of sand. Eventually we settled on a very static and manual approach that saved a few watts. 
One area of interest worth expanding on is the method of data transfer. It should be realized that passing everything around as a String is not the best idea. After all, you'd have to spend time parsing data out. Java objects might be a nice compromise, except they tend to take up a lot of memory, and still have an associated Class type. XML is my new go-to-guy. Storing a Document in a database is like saying there's molecules in my house, they could be anything. Documents are nice and generic, and support OOP designs. They enable a single-typed database that actually stores a range of different object types. Our API relies heavily upon the mysterious, but generic XML Document. Processes know how to access their designated Documents, and only their designated Documents. Thus, processes are the only thing responsible for knowing how to handle the Document's internal format. This helps to promote encapsulation, extensibility and information hiding.
...And now,I humbly offer these low-hanging fruits of wisdom regarding API design:
1. Figure out what's important.
Will energy savings trump extensibility and elegance of design? Is simplicity the better part of valor? Odds are you'll have to take one aspect at the cost of another. Figure it out before you start. It'll save you a long afternoon of face-palming.
2. Make sure the design is at least as extensible as it needs to be.
We made concessions in our extensibility because there's only so many sensors that a house can have (plus were on a budget). But make sure its flexible enough to grow.
3. Trace transactions from end to end.
We scrapped several ideas only after coding them, and then realizing they didn't work. Make sure the functionality is there.
4. "When in doubt, leave it out"
What does it mean? Who knows. But if you can find an applicable context, apply it!
5. Don't tell them how you did it.
A wise man once told me (I saw it on a Google Video) that users should never know exactly how a method does what it does, or else they may come to rely on it's process rather than it's result. For example, if you tell users how a hash value is calculated, they may use the hash function else where. If you ever change the hash function, you break their code.
No comments:
Post a Comment