This discussion about “bad APIs” was thoughtful and made me think of what a good one looks like. As I just wrote a book on the Github API I thought contrasting bad API with what I consider to be a good one makes sense.

Proper Versioning

The GitHub API does versioning well. You explicitly specify a header to say which version you want, and GitHub is very careful about updating the API, so your code won’t break. When they do, they are usually security fixes.

GitHub gets an A for their versioning.

Sandbox

Many APIs allow you to practice using their API in an online sandbox. Stack Overflow has a great example of this.

GitHub gets a B for this. They don’t offer a sandbox, but you can easily create a test repository and do anything you need to do on your production repository.

Using a test repository is documented in the Hubot chapter of the book.

Testability

At the 11th hour of submitting the final copy of the book, a reviewer noted “this hot mess does not work” regarding the Android chapter. In this chapter, I show how to write a small mobile application that writes data into a repository hosted on GitHub. This is a somewhat complicated process, where you need to write out trees, commit objects, and blobs. GitHub made a breaking change which plugged a minor identity hole, but it broke my code. Fortunately, each chapter in the book contains tests to prove the code works, and they helped me quickly identify the problem and fix it.

GitHub gets a B+ for an API that makes testing possible. There is little documentation or information on best practices to do this (something I hope my book fulfills) but the API is very complete and unsurprising, the foundation for testable code.