How to learn an API

Question

When I find some interesting project (e.g. on GitHub) I often would like to use it and try it out to see how it works, but if there isn't a good documentation or some kind of tutorial it's hard to figure out how to use it.

So my question is: how do you approach such a situation? How do you figure out which classes are important and how to chain them to put them to use? What would you look at first?

An advice I found is to look at the tests (if there are any). But if there are unit tests for every class, how do you know which ones to look at first?

Answer 1

Find code samples that use that API, then study them.

Why?

Unlike unit tests or reading the API inline documentation, code samples showcase an entire use-case for that API, start to finish. You can see precisely what the inputs and outputs are, and you can usually understand from the context what it is supposed to do. Even more complicated APIs can be deciphered this way, since you see the entire picture. It also makes sense - you are not concerned with internal library implementation details or how to test it, you are concerned with how to use the API, so you look at other programs that do that.

Where to find code samples featuring usage of the API?

Naturally the only code you will be able to find is open-source code. A good way to find relevant samples is to use a search engine for open-source code, such as Github Search or Koders. Another way to try and identify other project from the library's author, which are likely to use it.

Finally, you could also use sites such as Stackoverflow to ask for a code sample for a specific use-case, e.g. "how do I transmogrify zebras from low-quality to high-quality with the ZebraTransmogrifierHD library?"... or you could find existing questions there that ask for how to accomplish things.

What are the disadvantages?

The problem with looking at a code sample, as opposed to finding a tutorial, is that some lines might not be immediately understood by you, and yet you will be eager to try the API so you will reproduce the entire sample in your own code, including these lines. Having lines in your own code that you do not understand is a very bad idea!

What I do in those cases is to tinker with those mystery lines - what happens if I move them around? Remove them altogether? Change the parameters? etc.. This usually helps.

Answer 2

Completely undocumented APIs are not worth learning. If they were, someone would have documented them by now ;)

As far as applications go, you can at least look for entry point (Main class, a front controller in web app, etc.) and start reverse engineering from there.

Answer 3

OK you have no documentation...

You could ...

Determine a very simple use case that would require such an API. Then jump in and try and implement that use case using the API. Once your knowledge grows you can expand your usage of the API.

Find some sample code that uses the API.

Browse the API source code (if it's available). Look for entry points.

Google some of the API classes, method, functions, ...

Answer 4

As @Mchi has mentioned, completely undocumented APIs are not worth learning. That implies not even using it. For use to your projects always consider the popular ones - the deal being you can always find support to it in some forum or other.

Answer 5

First thing you should check is what the entry points are. If you know what those are, you can create some integration tests. With the information you are getting from these tests you can see how the API works and behaves on certain input.

What's also nice, is you've got tests in place before even writing a single piece of code for your project. That way you will always know your application will work with the API or not (after an update or something).

Answer 6

Write your own tests for the API like Uncle Bob described in his book Clean Code.

The test will help you learn the usage of the API and possible weaknesses.

When the API is changed later than you have your test to fallback on.

It's easier to do than prototyping an application.