How to deal with an Undocumented API/Framework under .NET?

Question

For work I have to code with an external company's API to deal with their proprietary database solution. Unfortunately the documentation they provide is more of an example guide then proper API docs, so it is very light on nitty gritty details like error codes, method returns, and exceptions.

So for instance, a class will have a .GetErrorCode() method, but I have no idea what those error numbers mean because they didn't document what number matches up with what error. In many cases a method will return an Object, with no documentation of what the type of Object it actually returns. I have asked them repeatedly for proper documentation but they seem to details like the ones above are propriety secrets. So, is there any tools or methods I can work around my limited or in some cases non-existent documentation.

Please note that I am using Visual Studo 2005 and coding in C# under .Net.

And before anyone answers, "don't use the API", I have to, it is for work.

Answer 1

Best tools that come to mind include phone and e-mail. Hopefully you can keep bugging people over there until they give you more useful info... :(

Answer 2

If I can't get code samples or talk to an original developer, I usually resort to Reflector to look at the underlying code. It's slow and inefficient, but sometimes that's all you can do.

Answer 3

Use Reflector to see the source code. Should show you the Enum for the GetErrorCode message.

Reflector, by the way, is the greatest program in the history of the universe.

Answer 4

A nasty scenario. I hate to suggest it, but maybe reflector is your friend if it isn't obfuscated. There may be some IP issues, but in this case reversing it seems the only viable way of finding out what the API is. However, I suspect (from methods like .GetErrorCode()) that this is a shim on top of P/Invoke - in which case even reflector will just show you lots of external calls...

The main other thing I can say is: write lots of unit tests that cover how you are trying to use it... that way if you guess wrong and something changes, you'll know early.

Answer 5

It depends on your situation. If you're paying for the API, you should continue to pressure the company for better documentation of how to use the API.

If that won't work, what I would do is start my own documentation as I develop. Keep a notebook, a personal Wiki (screwturn wiki comes to mind), or some sort of electronic documentation. As some other people mentioned, you can use Reflector to help get to the source (if it's not obfuscated).

Creating your own documentation may not be what you were looking for, but if you can't get real documentation, at least create some as you learn things so that you can have something to guide you a few months (or years) down the road when you're trying to maintain the code built with the API.