Over the course of the next few weeks, I will be blogging about my experiences with a few APIs I have been using to build OverVue. The focus will mainly be around authentication and webhooks, Ruby and any 3rd party gems used. I will try and keep the reviews light on Ruby code or specific gem usage to make these as general to the API quality as I can. In addition to the GitHub review here, I will also be reviewing Trello’s API, Slack’s, HipChat’s, Bitbucket’s, Asana’s and JIRA’s(I will link out to them as they become complete).

I am using the GitHub API to collect commit and pull request events via webhooks to coalesce those events with Overvue channels and users. Providing insight into how a team, project or user is doing in correlation to the status and commentary to a report.

I’ll be starting off with what might have been the most pleasurable of the APIs I dealt with, GitHub’s. It’s an API developers dream of, with great documentation, pretty strong adherence to API standards and endpoints that have most of the data needed to keep it all under one API request.

Documentation

GitHub has some of the best API documentation I have seen, and I have dealt with quite a few APIs in my career. Their navigation is pretty straightforward on the left side, with main topics that expand into individual subtopics that may link to separate pages or anchors within a page. The actual documentation is thorough, without being overly verbose at most times. When an API request is discussed, there is an example request and response, including(most times) an in-depth breakdown of the attributes included in the response. Along with documentation on the API itself, there is an additional section guide for Webhooks, a full section for guides, and a section to libraries(both official and unofficial) in various languages to the GitHub API.

Authentication

Adding a developer application was simple enough as following a link in the Overview portion of their documentation to fill out a few small fields to get the necessary credentials to hook up authentication. GitHub’s API allows Basic Authentication but recommends and gently pushes you towards OAuth2. GitHub follows the standard OAuth approach to direct the user to page on GitHub’s servers to accept the access request and redirect back to the 3rd party site/app. With an access token in hand from the OAuth handshake and the GitHub gem, you can now make requests to get information about repos, organizations, etc that are within the scopes you chose during the OAuth handshake.

API/Gem

While not using the GitHub gem extensively, I have used it for accessing the webhook set up programmatically and basic repo listing. The usage was fairly straightforward by providing an authenticated Webhooks object repo information to perform CRUD(Create Read Update Delete) operations. While I haven’t gone much further outside of my particular use case, both the gem and it’s respective endpoints seem clear and easy to use.

Webhooks

Webhooks play an integral part in OverVue’s event integrations. Setting up webhooks allow the 3rd party services to contact OverVue endpoints to insert events into the database. The events are then sliced and diced into other resources such as channels. Github’s webhook API, guides, and general use have been very pleasurable to work with.

Github’s webhook guide guides you through the events you can receive ranging from commits to pull requests to issues and comments. Then through the setup of webhooks, both through the settings UI inside GitHub or links to the API documentation. With the guides recommendation of ngrok, detailed demonstrations of webhook payloads and a detailed explanation of how webhook security works, GitHub wants to make sure no stone is left unturned in the understanding of how their webhooks work.

API Grade

I suppose I can end each review with a grade of some sort. It will be completely subjective and won’t provide much more than a comparative view on my opinions between APIs used at OverVue. With that being said, I would give the GitHub API an…

A