GitHub is an awesome platform for maintaining Git sources and tracking project issues. I moved all my projects (both private and public) to GitHub about three years ago and have no regrets. Moreover, GitHub gives access to almost all of its features through RESTful JSON API.
There are a few Java SDK-s that wrap and expose the API. I tried to use them, but faced a number of issues:
- They are not really object-oriented (even though one of them has a description that says it is)
- They are not based on JSR-353 (JSON Java API)
- They provide no mocking instruments
- They don't cover the entire API and can't be extended
Keeping in mind all those drawbacks, I created my own library—jcabi-github. Let's look at its most important advantages.
Object Oriented for Real
GitHub server is an object. A collection of issues is an object, an individual issue is an object, its author is an author, etc. For example, to retrieve the name of the author we use:
Needless to say,
User are interfaces. Classes that implement them are not visible in the library.
MkGitHub class is a mock version of a GitHub server. It behaves almost exactly the same as a real server and is the perfect instrument for unit testing. For example, say that you're testing a method that is supposed to post a new issue to GitHub and add a message into it. Here is how the unit test would look:
This is much more convenient and compact than traditional mocking via Mockito or a similar framework.
It is based on JSR-353 and uses
jcabi-http for HTTP request processing. This combination makes it highly customizable and extensible, when some GitHub feature is not covered by the library (and there are many of them).
For example, you want to get the value of
hireable attribute of a
User.Smart doesn't have a method for it. So, here is how you would get it:
We're using method
json() that returns an instance of
JsonObject from JSR-353 (part of Java7).
No other library allows such direct access to JSON objects returned by the GitHub server.
Let's see another example. Say, you want to use some feature from GitHub that is not covered by the API. You get a
Request object from
GitHub interface and directly access the HTTP entry point of the server:
All classes are truly immutable and annotated with
@Immutable. This may sound like a minor benefit, but it was very important for me. I'm using this annotation in all my projects to ensure my classes are truly immutable.
A few days ago we released the latest version 0.8. It is a major release, that included over 1200 commits. It covers the entire GitHub API and is supposed to be very stable. The library ships as a JAR dependency in Maven Central (get its latest versions in Maven Central):