Watch out for the APIs

There’s an old saying in the computer industry that says you should be lenient with what you receive and accurate with what you give, mainly it means that when parsing data you receive, it’s not uncommon to receive bad input, so it would be nice of you to either tell the program or person that generated the error that they did something wrong, try to correct the data or use a default.

Back in the real world though, writing software has taught me that this is just saying that gets ignored to several degrees by almost every API. My guess is that once the spec is done, no one actually bothers to actually whatever comes out. This post serves as a list for the problems people seem to ignore when they  make an API for C++.

Let’s start with a little bit of math, for those not very interested in 3D concepts, a Quaternion is a 4 element vector that you can turn into a rotation matrix. It basically represents the rotation around an axis, so when you see a Quaternion class with a constructor that looks like the following:

Quaternion(double, Vector3&);

your natural reaction would be to assume that it initializes the new quaternion so that it represents the rotation specified by the double argument around the axis represented by the Vector class, right ? Well as it turns out, it more often than not it just copies the values into its’ members. How on earth is that more useful than something that it was created for is beyond me, but that’s probably because I’ve actually used quaternions.

Moving on to some geometry, when you’re working with images you’re bound to run into something that requires coordinates. Now there are a lot of ways to say where an image begins and where it ends, but fortunately only two of them are used in practice. Most of you have probably seen the one where coordinates start in the upper left corner and go toward the bottom right as they increase, so for instance if you have a resolution of 1280 x 800, then the bottom right corner is (1280, 800). The second one is the mathematical one where images start in the bottom left corner and go towards the upper right, however this one is seldomly present in libraries, so if you insist that the Y axis should be up because that’s how things were in highschool, then at least leave a comment to let the rest of the world know that the top should be bigger than the bottom of the image in order for something to work.

And last, but not least, never ever use STL in an API, ever. Containers are awesome for programming in general, I agree, but when you want to send data from one dll to another you have to keep in mind that the people making the other library are sometimes using other tools than your own, and containers are almost never compatible between toolsets, something always crashes sooner or later unless everyone uses the same compiler and linker, in theory that’s not much of a problem, in practice however you’re often forced by the environment you’re developing for to use certain tools if you want to be able to debug your application. So in the end it all comes down to either using some really awkward hacks to be able to accommodate the library or dropping that library altogether. This is why nice, clean APIs are usually made in C, well that and no name mangling to take into account when importing functions by hand.

So yeah, making an API isn’t as easy as one would originally assume, however if you have some patience and are lenient with what you expect from it sometimes it’s not that bad, after all everyone makes mistakes, they’re ok so long as you learn to recognise them early.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s