
* 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.
- HMAC-SHA1 and PLAINTEXT signatures.

It depends on the following Guile version and modules:

- [[http://www.gnu.org/software/guile/][Guile]] >= 2.2.0.
- [[http://www.gnutls.org/][GnuTLS]] Guile bindings (for HTTPS support).


* Installation

Download the latest tarball and untar it:

- [[http://download.savannah.gnu.org/releases/guile-oauth/guile-oauth-0.4.0.tar.gz][guile-oauth-0.4.0.tar.gz]]

If you are cloning the repository make sure you run this first:

    : $ autoreconf -vif

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

** 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.


** 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 "https://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 tweet "text"))) tweets)


* License

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

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.  This file is offered as-is,
without any warranty.

Copyright (C) 2013-2018 Aleix Conchillo Flaque <aconchillo@gmail.com>
