REST API

The Barkeep server has a RESTful HTTP API for retrieving data programmatically (e.g. with the Barkeep client).

Id	HTTP Method	Route	Required parameters	Optional parameters	Authentication required	Admin only
1	POST	/api/add_repo	url	none	yes	yes
2	GET	/api/commits/{repo_name}/{sha}	none	fields	no	no
3	POST	/api/commits/{repo_name}	shas	fields	no	no
4	POST	/api/comment	repo_name, sha, text	file_name, line_number	yes	no

Details

1. This route adds a git repo to Barkeep for tracking. You must sign this request (see Authentication, below) and you must be an admin user.

2. This gives the user information about a single commit. The sha may be a prefix of the full sha. The result is a JSON-formatted map:

   {
   "approved": [boolean],
   "approved_by": [user name and email (string)],
   "approved_at": [unix timestamp (int)],
   "comment_count": [number of comments (int)],
   "link": [link for viewing this commit (string)]
   }
   

   If the optional fields parameter (a comma-separated list of field names) is given, then only the corresponding fields will be in the result. For instance, you might only care about approval, so you can pass &fields=approval with the request.

3. This is very similar to 2. The purpose of this request is to allow for requesting information about many commits in big batches. For this reason, it must be a POST (GETs do not work well if they are very large). The shas parameter is a comma-separated list of commit shas. fields functions the same way as in 2. The result is a map where the keys are the full shas of the commits and the values are the same as in 2:

   {
   "7504a2ace8fff8f9eded99e5ea633bd7be40285d": { "approved": false, ... },
   "3b42b44fa73ade36e566724faf498e1c9c9769d0": { ... },
   ...
   }
   

4. This route allows for posting comments, so you must sign the request (see Authentication, below). You may post a commit-level comment by leaving out filename and line_number, and only giving a repo_name and sha.

Authentication

Some API requests allow you to perform actions as a user, and therefore must be authenticated. This is done by including a signature with the request. The scheme we use is similar to AWS and other web services. To sign a request, you will need your API key and API secret. You can find these by logging into Barkeep and going to 'settings'.

To sign a request, add the new query-string parameters timestamp, with the value equal to the current Unix time, and api_key, containing your API key. Now you need to construct the canonical string representation of your query. Sort all the parameters to your request lexicographically, url-escape them, and then arrange them in normal query-string fashion (i.e. with ? and &s) after the route. The canonical string is

{METHOD} {route}{parameters}

Take the HMAC-SHA1 in hex of your API secret with this string, and add that as the value to a key called signature to your list of parameters as well. Now you can make the request. After 5 minutes, the request will be stale and you will have to make a new one with a fresh timestamp and re-sign it.

Example

Suppose we have the following API key and secret:

API key: APIKEY
API secret: APISECRET

Suppose we wish to post a comment to commit 9df81d a repository called "project51". (Note that you need to use the full SHA, but we will use a truncated one for demonstration puposes.) We would use API route 4, above. The route will be /api/comment and the parameters will be

repo_name=project51&sha=9df81d`.

• Find the current Unix time: 1335785915

• Append the timestamp and API key parameters:

    repo_name=project51&sha=9df81d&timestamp=1335785915&api_key=APIKEY
  

• Sort the key-value pairs by the keys, lexicographically:

    api_key=APIKEY&repo_name=project51&sha=9df81d&timestamp=1335785915
  

• Construct the canonical string by combining this with the HTTP method and route:

    POST /api/comment?api_key=APIKEY&repo_name=project51&sha=9df81d&timestamp=1335785915
  

• Take the HMAC-SHA1 in hex of the API secret with this string. In ruby, this may be done with the following code using openssl:

  require "openssl"
  OpenSSL::HMAC.hexdigest("sha1", secret, canonical_string)

• Append the signature to the list of parameters and make the request. In this case, the parameters would be:

    repo_name=project51&sha=9df81d&timestamp=1335785915&api_key=APIKEY&signature=7a1f453b23b38a31956b1eeea9d876b8603c39c6