This is a Clojure library for accessing the Twitter API using http.async.client.
It endeavors to implement all Twitter APIs:
It is tested by interacting with the live Twitter API.
- I felt the current offerings were a bit out of date
- I wanted the efficiency of the async comms libraries
- I needed some stuff from the headers returned by twitter (i.e. the rate-limiting stuff and etag)
- I wanted full API coverage (restful, streaming and search)
http.async.clientby Hubert Iwaniukclj-oauthby Matt Revelle
twitter-api is published on Clojars.
Add the following to your project.clj's :dependencies:
[twitter-api "1.8.0"]
All of the functions follow Twitter's naming conventions; we convert a resource's path into the function name. For example:
https://api.twitter.com/1.1/account/settingsis available asaccount-settingshttps://api.twitter.com/1.1/statuses/update_with_mediais available asstatuses-update-with-media
Parameters are uniform across the functions. All calls accept:
:oauth-credsis the result of themake-oauth-credsfunction.:paramsis a map of parameters to pass, e.g.,?list_id=123would be{:list-id 123}:headersadds or overrides any of the request headers sent to Twitter.:verboverrides the HTTP verb used to make the request, for resources that support it (e.g.,account-settings):callbacksattaches a custom callback to the request.
All of the API calls return the full HTTP response, including headers, so in most cases you will want to get the response's :body value.
(ns mynamespace
(:use [twitter.oauth]
[twitter.callbacks]
[twitter.callbacks.handlers]
[twitter.api.restful])
(:import [twitter.callbacks.protocols SyncSingleCallback]))
(def my-creds (make-oauth-creds *app-consumer-key*
*app-consumer-secret*
*user-access-token*
*user-access-token-secret*))
; simply retrieves the user, authenticating with the above credentials
; note that anything in the :params map gets the -'s converted to _'s
(users-show :oauth-creds my-creds :params {:screen-name "AdamJWynne"})
; supplying a custom header
(users-show :oauth-creds my-creds :params {:screen-name "AdamJWynne"} :headers {:x-blah-blah "value"})
; shows the users friends
(friendships-show :oauth-creds my-creds
:params {:target-screen-name "AdamJWynne"})
; use a custom callback function that only returns the body of the response
(friendships-show :oauth-creds my-creds
:callbacks (SyncSingleCallback. response-return-body
response-throw-error
exception-rethrow)
:params {:target-screen-name "AdamJWynne"})
; post a text status, using the default sync-single callback
(statuses-update :oauth-creds my-creds
:params {:status "hello world"})
; upload a picture tweet with a text status attached, using the default sync-single callback
; (this method has been deprecated by twitter.)
(statuses-update-with-media :oauth-creds my-creds
:body [(file-body-part "/pics/test.jpg")
(status-body-part "testing")])
;; upload a picture tweet.
(let [media-id (-> (media-upload-chunked :oauth-creds my-creds
:media "/pics/test.jpg"
:media-type "image/jpeg")
:body
:media_id)]
(statuses-update :oauth-creds my-creds :params {:status "hi!" :media-ids [media-id]}))
;; upload a video tweet.
(let [media-id (-> (media-upload-chunked :oauth-creds my-creds
:media "/vids/test.mp4"
:media-type "video/mp4")
:body
:media_id)]
(statuses-update :oauth-creds my-creds :params {:status "hi!" :media-ids [media-id]}))(ns mynamespace
(:use [twitter.oauth]
[twitter.callbacks]
[twitter.callbacks.handlers]
[twitter.api.streaming])
(:require [clojure.data.json :as json]
[http.async.client :as ac])
(:import [twitter.callbacks.protocols AsyncStreamingCallback]))
(def my-creds (make-oauth-creds *app-consumer-key*
*app-consumer-secret*
*user-access-token*
*user-access-token-secret*))
; retrieves the user stream, waits 1 minute and then cancels the async call
(def ^:dynamic *response* (user-stream :oauth-creds my-creds))
(Thread/sleep 60000)
((:cancel (meta *response*)))
; supply a callback that only prints the text of the status
(def ^:dynamic
*custom-streaming-callback*
(AsyncStreamingCallback. (comp println #(:text %) json/read-json #(str %2))
(comp println response-return-everything)
exception-print))
(statuses-filter :params {:track "Borat"}
:oauth-creds my-creds
:callbacks *custom-streaming-callback*)-
Unlike other APIs, the parameters for each call are not hard-coded into their Clojure wrappers. I just figured that you could look them up on the dev.twitter.com/docs and supply them in the
:paramsmap. -
You can authenticate or not, by including or omitting the
:oauth-credskeyword and value. The value should be atwitter.oauth.OauthCredentialsstructure (usually the result of thetwitter.oauth/make-oauth-credsfunction) -
The callbacks decide how the call will be carried out - be it a single or streaming call, or an async or sync call. Read
twitter.callbacks.protocolsto see how it works -
You can declare new methods that use different callbacks by either supplying them to the
def-twitter-methodmacro, or inline at run time (via the:callbackskey/value), or both! -
Unless you supply a
:client my-clientpair, the library will use a memoized client. This normally won't be a problem if you don't need to exit gracefully (i.e., without(System/exit 0)or Ctrl-C), but otherwise may cause your program to hang unexpectedly. To avoid this, you must do a bit more bookkeeping, via either one of these workarounds:-
Create and close your own client:
(with-open [client (http.async.client/create-client)] (users-show :client client :oauth-creds my-creds :params {:screen-name "AdamJWynne"}))
-
When you're done making API calls, close the memoized client:
(http.async.client/close (twitter.core/default-client))
-
Use leiningen to build the library into a jar with:
$ git clone git:https://github.com/adamwynne/twitter-api.git
Cloning into twitter-api...
remote: Counting objects: 167, done.
remote: Compressing objects: 100% (115/115), done.
remote: Total 167 (delta 68), reused 125 (delta 26)
Receiving objects: 100% (167/167), 33.60 KiB, done.
Resolving deltas: 100% (68/68), done.
$ cd twitter-api/
$ lein jar
Which produces a jar file at target/twitter-api-*.jar.
The tests require that credentials be provided via environment variables with the following names:
export CONSUMER_KEY=l4VAFAKEFAKEFAKEpy7R7
export CONSUMER_SECRET=dVnTimJtFAKEFAKEFAKEFAKEFAKEFAKEBVYnO91BR1G
export SCREEN_NAME=twitterapibot
export ACCESS_TOKEN=195648015-OIHb87zuFAKEFAKEFAKEFAKEFAKEFAKEb5aLUMYo
export ACCESS_TOKEN_SECRET=jsVg1HFAKEFAKEFAKEFAKEFAKEFAKE4yfOLC5cXA9fcXrThen simply run lein test, which takes about a minute since many of the tests involve calling the Twitter API and waiting for an appropriate response.
If all tests completed successfully, the test output will end with a message like:
Ran 47 tests containing 123 assertions.
0 failures, 0 errors.
This library made open-source by StreamScience
Follow @AdamJWynne and @StreamScience to save kittens and make rainbows.
Copyright (C) 2011 StreamScience
Distributed under the Eclipse Public License, the same as Clojure.