
* guile-oauth

guile-oauth is a simple OAuth client module for Guile. It supports the
following features:

- OAuth 1.0 ([[http://tools.ietf.org/html/rfc5849][RFC 5849]]) protocol support.
- HTTP and HTTPS.
- HMAC-SHA1 and PLAINTEXT signatures.

It depends on the following Guile version and modules:

- [[http://www.gnu.org/software/guile/][Guile]] 2.0.9.
- [[http://www.gnutls.org/][GnuTLS]] Guile bindings (for HTTPS support).
- [[http://weinholt.se/industria/industria.html][Industria]] (for HMAC-SHA1 signatures).


* Installation

guile-oauth is freely available for download under the terms of the GNU
Lesser General Public License version 3 (LGPLv3).

Download the latest tarball and untar it:

- [[http://hacks-galore.org/aleix/guile-oauth/guile-oauth-0.1.1.tar.gz][guile-oauth-0.1.1.tar.gz]]

Then, run the typical sequence:

    : $ ./configure --prefix=<guile-prefix>
    : $ make
    : $ sudo make install

Where <guile-prefix> should preferably be the same as your system Guile
installation directory (e.g. /usr).

If everything installed successfully you should be up and running:

    : $ guile
    : scheme@(guile-user)> (use-modules (oauth oauth1))
    : scheme@(guile-user)>

It might be that you installed guile-oauth somewhere differently than
your system's Guile. If so, you need to indicate Guile where to find
guile-oauth, for example:

    : $ GUILE_LOAD_PATH=/usr/local/share/guile/site guile


* Usage

** Example: Twitter client

The following example details how to obtain the tweets of your Twitter
home timeline. The complete example is available as a web application
under the /examples/ directory.

- Load the OAuth and JSON modules:

    : > (use-modules (oauth oauth1) (json))

- Define our Twitter URLs and application credentials:

    : > (define request-url "https://api.twitter.com/oauth/request_token")
    : > (define authorize-url "https://api.twitter.com/oauth/authorize")
    : > (define access-url "https://api.twitter.com/oauth/access_token")
    : > (define home-timeline "http://api.twitter.com/1.1/statuses/home_timeline.json")
    : > (define credentials (oauth1-credentials key secret))

  The /key/ and /secret/ are provided by Twitter once you register a
  new application at https://dev.twitter.com.

- Obtain a request token:

    : > (define request-token (oauth1-client-request-token request-url credentials))

- Connect to the following returned URL for authorizing the request token:

    : > (oauth1-client-authorize-url authorize-url request-token)

  Here you will need to login to Twitter or simply authorize your
  application if you are already logged in.

- Obtain the access token that will allow us to access protected resources:

    : > (define access-token
    :     (oauth1-client-access-token access-url credentials request-token verifier))

  The /verifier/ is the string given by Twitter in the previous step.

- Get your tweets:

    : > (define result (oauth1-client-request home-timeline credentials access-token)

- Parse the tweets with JSON and get a list of user/tweet pairs:

    : > (define tweets (json-string->scm result))
    : > (map (lambda (tweet) (cons (hash-ref tweet "user") (hash-ref twee "text"))) tweets)


** Procedures

These are the main procedures for guile-oauth which are implemented in
terms of other guile-oauth procedures you will find in the API.

- (*oauth1-client-request-token* url credentials) Obtain a request token
  from the server url for the given client credentials.

- (*oauth1-client-authorize-url* url token) Returns a complete authorization
  URI given the server url and a request token.

- (*oauth1-client-access-token* url credentials token verifier) Obtain
  an access token from the server url for the given client
  credentials, request token and verifier.

- (*oauth1-client-request* url credentials token) Access a server's
  protected resource url with the given client credentials and an access
  token.
