So you've entered the wild rainforest of someone's new API. How do you find your way through?

Question

Got any tips for me with regards to figuring out new APIs? I'm trying to overcome my irrational fear of properly learning to work with other peoples' code, so I can seriously use all the advice I can get!

Answer 1

Unit Tests help immensely, as Bill said. I usually try to find the small set of classes that act as entry points. A good example of this is the IWindsorContainer for CastleWindsor , MockRepository in RhinoMocks, or the ISession, ISessionFactory, Configuration combo in NHibernate.

After that I will then fire up Reflector and look at some of the more interesting bits to see how things work if the "entry" classes are not clear enough.

Answer 2

Duplicate?

Answer 3

I skim through the docs and start using it. I also find people that has used the API and forums about the new API and ask for quick tutorials.

If the API has published it's unit test code, then I start by reading that to get myself familiarised on how to use it. If it doesn't have those, I start writing one for my use - one by one - recording the things that I am learning using tests.

The quickest way to learning a new API is to just use it.

Answer 4

If it's C++, and you are Windblows, the free Visual C++ Express is a wonderful thing. On Java, Eclipse is just ultimate

For going in details of what calls what, i find valgrind and gdb to be best companion.

Another good options is run thru doxygen, and look at various dot'ted diagram it creates.

However, having a concrete 'to do thing' is essential, or it's easy to just get lost in maze.

Answer 5

1) Read the documentation. The documentation for API's is almost always wrong, or incomplete in ways that will trip you up, but it's worth doing to get a general roadmap.

2) As Bill the Lizard said above, read the unit tests. If they are well written, they will provide a skeleton for how the API is meant to be used and what assumptions are valid. If they aren't well written, you may wish to reconsider using the API. If you don't have unit tests, find working examples to dissect. Don't copy examples exactly. They are almost always wrong in some way that will bite you later, and you won't really have learned anything about the API.

3) Write some code. Start simple. Call one function. When it doesn't do what you expect, iterate. These don't have to be unit tests, but if you do write unit tests, you'll have your own personal documentation of what you understand about the library. I like writing command line console apps that let me throw different things at the API as a first step. The less time it takes between the question "what happens if..," and the answer, the better.

4) When you have a problem, ask somebody. If it's an in-house API, call up the guy who wrote it. If not, the internet is a great resource for software questions, and every API has a community of enthusiasts that are generally happy to welcome someone who asks good questions to the fold.

Repeat 3 and 4 until you are comfortable with the API.