Skip to content
100644 67 lines (41 sloc) 6.29 KB
4b5d42c @Raynes Docs.
Raynes authored
1 # An octocat is nothing without his tentacles
2b0ee17 @Raynes First commit.
Raynes authored
4b5d42c @Raynes Docs.
Raynes authored
3 Tentacles is a Clojure library for working with the Github v3 API. It supports the entire Github API.
2b0ee17 @Raynes First commit.
Raynes authored
2723fb9 @Raynes More info.
Raynes authored
5 This library is the successor to my old [clj-github]( library. It will no longer be maintained.
2b0ee17 @Raynes First commit.
Raynes authored
7 ## Usage
e0e49c9 @Raynes Updated readme with new info.
Raynes authored
9 This is on clojars, of course. Just add `[tentacles "0.1.3"]` to your `:dependencies` in your project.clj file.
4b5d42c @Raynes Docs.
Raynes authored
11 ### CODE!
13 The library is very simple. It is a very light wrapper around the Github API. For the most part, it replaces keywords with properly formatted keywords, generates JSON for you, etc. Let's try out a few things.
15 ```clojure
16 user> (user-repos "amalloy")
17 ; Evaluation aborted.
18 user> (repos/user-repos "amalloy")
19 [{:fork false, :pushed_at "2010-12-10T07:37:44Z", :name "ddsolve", :clone_url "", :watchers 1, :updated_at "2011-10-04T02:51:53Z", :html_url "", :owner {:avatar_url "", :url "", :gravatar_id "1c6d7ce3810fd23f0823bf1df5103cd3", :login "amalloy", :id 368685}, :language "Clojure", :size 1704, :created_at "2010-08-18T16:37:47Z", :private false, :homepage "", :git_url "git://", :url "", :master_branch nil, :ssh_url "", :open_issues 0, :id 846605, :forks 1, :svn_url "", :description "Double-dummy solver for contract bridge"} ...]
20 ```
22 I cut out most of the output there. If you try it yourself, you'll notice that it produces a *ton* of output. How can we limit the output? Easily!
24 ```clojure
25 user> (repos/user-repos "amalloy" {:per-page 1})
26 [{:fork false, :pushed_at "2010-12-10T07:37:44Z", :name "ddsolve", :clone_url "", :watchers 1, :updated_at "2011-10-04T02:51:53Z", :html_url "", :owner {:avatar_url "", :url "", :login "amalloy", :gravatar_id "1c6d7ce3810fd23f0823bf1df5103cd3", :id 368685}, :language "Clojure", :size 1704, :created_at "2010-08-18T16:37:47Z", :private false, :homepage "", :git_url "git://", :url "", :master_branch nil, :ssh_url "", :open_issues 0, :id 846605, :forks 1, :svn_url "", :description "Double-dummy solver for contract bridge"}]
27 ```
29 This time we actually *did* get just one item. We explicitly set the number of items allowed per page to 1. The maximum we can set that to is 100 and the default is 30. We can get specific pages of output the same way by using hte `:page` option.
31 This also introduces an idiom in tentacles: options are a map passed to the last parameter of an API function. The options map also contains authentication data when we need it to:
33 ```clojure
34 user> (repos/repos {:auth "Raynes:REDACTED" :per-page 1})
35 [{:fork true, :pushed_at "2011-09-21T05:37:17Z", :name "lein-marginalia", :clone_url "", :watchers 1, :updated_at "2011-11-23T03:27:47Z", :html_url "", :owner {:login "Raynes", :avatar_url "", :url "", :gravatar_id "54222b6321f0504e0a312c24e97adfc1", :id 54435}, :language "Clojure", :size 180, :created_at "2011-11-23T03:27:47Z", :private false, :homepage "", :git_url "git://", :url "", :master_branch nil, :ssh_url "", :open_issues 0, :id 2832999, :forks 0, :svn_url "", :description "A Marginalia plugin to Leiningen "}]
36 ```
38 If an API function has no options and authentication would have no uses for that particular call, the options map is not a parameter at all. For API calls that can do different things based on whether or not you are authenticated but authentication is not **required**, then the options map will be an optional argument. For API calls that require authentication to function at all, the options map is a required argument. Any data that is required by an API call is a positional argument to the API functions. The options map only ever contains authentication info and/or optional input.
e0e49c9 @Raynes Updated readme with new info.
Raynes authored
40 Authentication information can be basic auth info (username:password) as demonstrated above or it can be an oauth2 access token. In that case, you'd pass the `:oauth-token` key instead.
42 The Github API is massive and great. I can't demonstrate every API call. Everything is generally just as easy as the above examples, and I'm working hard to document things as well as possible, so go explore!
44 Here are some lovely [Marginalia docs]( I also wrote a demonstrational [blog post]( about Tentacles that I intend to keep updated with future releases.
4b5d42c @Raynes Docs.
Raynes authored
46 If you run into something that isn't documented well or you don't understand, look for the API call on the Github API [docs]( If you feel like it, please submit a pull request with improved documentation. Let's make this the most impressive Github API library around!
2b0ee17 @Raynes First commit.
Raynes authored
4d4626b @Raynes Info about running the tests.
Raynes authored
48 ## Hacking
50 ### Running the tests
52 In order to run the tests, you need to create a `testinfo.clj` in the root of the checkout with some info required for the tests to run properly. This file is ignored by git, so don't worry about committing auth info. This file should contain a Clojure map like the following:
54 ```clojure
55 {:user "" ;; Github username
56 :pass "" ;; Github password
57 :follows ""} ;; Username of a person that this user follows.
58 ```
60 As more tests are written this information may grow.
2b0ee17 @Raynes First commit.
Raynes authored
62 ## License
f2d32be @Raynes README!
Raynes authored
64 Copyright (C) 2011 Anthony Grimes
2b0ee17 @Raynes First commit.
Raynes authored
66 Distributed under the Eclipse Public License, the same as Clojure.
Something went wrong with that request. Please try again.