Designing a good API

So I've been doing some work porting some code to another platform (which I'll speak about later), and it's showing a severe lack of API design. Now I design APIs for a living I thought I'd quickly go over what I think makes a good API, not just from a users point ov view, but internally as well.

Simple and Fast. And we're done. Thanks for reading.

Okay... I'll go into a litte more detail. Now, API's are usually there to give a coder simple access to a more complex system. Take DirectX. The underlying hardware and systems are pretty complex these days, what with interrups, DMA chains dynamic memory management and all the rest of it, yet the API is (reasonably) simple. So... here goes.

Simple. An API must be simple, in fact as simple as you can get away with. This isn't to say you should make it basic, no. You should make it do everything a coder will normally have to do, but don't over complicate it by using 1,000,000 calls for each function. Take DirectX texture creation... Now, whenever I do a graphics engine I have a single CreateTexture() function where as DirectX has several. Textures, Surfaces, DepthBuffers and Cube Maps, the list goes on. Now why? Theres really no reason for that kind of split. You could just as easily use flags and paramaters to allow the various types of selection. This means the coder only has a single function to learn, and if you follow this kind of rule for the whole API, then the entire system becomes much smaller. After all, would you rather a 1,000 call API where you have to set the width and height of a texture indavidually, or 10 functions that can do everything! The smaller the API, the more control you can keep over it. If you give access to every single function and variable, then it becomes a nightmare to change or upgrade.

So, keep an API simple. It's less to maintain, and the programmers that use it will thank you for it.

Speed. This is obvious. It has to be fast. If your management code gets in the way, then the API will become too expensive for coders to use properly, and they'll end up writing support functions themselves. This is really bad. You want the programer to have confidence in the API, not only that it'll do what you say it'll do, but that it won't slow him down. Streamline as much as possible, remove as many if's and but's as you can inside performance critical areas.

Now, a quick word about abstraction. It's important to abstract certain types of API so that it's clean and portable. Now theres a few of reasons for that. First you expect the API to change under you. If your using some open source interface, you never know when the latest buzz word is gonna take hold and your whole API is gonna change, so a simple layer of abstraction will protect you. Next, it will allow you to add value to an underlying API. Take DirectX texture management, if you add a simple layer to your API, you could then now keep track of all your textures, and it'll allow your to manage things like device resets (when you resize the window etc.) as since you own all the texture pointers you can free/reallocate things like render targets automatically. Lastly... Portability. Now most hobby projects don't care about this, but you never know when your project might take off and someone else might want to port it for you to a Mac, or a ZX81...or something.

The program I'm currently working on was hard coded for windows, using not only MFC, but DirectX calls and enums directly. So, being someone that designs APIs, I know all about abstraction. Being someone who's worked on lots of multi-platform games, I know all about how to make an API platform independent. So, thats what I'm doing. All calls to DirectX and being put through a layer of abstraction, each ENUM is being changed to be platform agnostic. This means the API can translate (very quickly) to whatever rendering API I want, without the main application knowing, or caring. The classic case is DirectX and OpenGL. Doing this would allow this program to run on the Mac, without the main program changing. I'd only have to port the (now pretty small) API, and not the whole program.

If you've done your job correctly, you'll have to port a handful of API's. Sound, Graphics, Networking and simples file systems and memory management. All games can be based on these simple API's, and then be made to run on other platforms (reasonably) easily.

Theres obviously lots of ideas for each API. Designing graphics APIs is an art in itself. I've used the same API for the last 10 years. The underlying graphics systems have been PS2, XBox 1, DirectX 8&9 and I know it would work just as well on a PS1, XBox360 (never seen a Ps3 SDK), and DX10/11. A well designed API will work on any platform and be a pleasure to use.

So there you go... Keep an API simple - don't get sucked into the latest fad. Keep if as fast as you possibly can. And abstract to reasonably protect yourself from underlying systems and to allow simple porting.