
* guile-oauth

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

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

It depends on the following Guile version and modules:

- [[https://www.gnu.org/software/guile/][Guile]] >= 2.2.0.
- [[https://www.gnutls.org/][GnuTLS]] Guile bindings (for HTTPS support).
- [[https://notabug.org/cwebber/guile-gcrypt/][guile-gcrypt]] >= 0.3.0.
- [[https://github.com/aconchillo/guile-json/][guile-json]] >= 3.0.0 (only to run Twitter example).


* Installation

Download the latest tarball and untar it:

- [[http://download.savannah.gnu.org/releases/guile-oauth/guile-oauth-0.5.0.tar.gz][guile-oauth-0.5.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 module:

    : > (use-modules (oauth oauth1))

- 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:

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

* License

Copyright (C) 2013-2020 Aleix Conchillo Flaqué <aconchillo@gmail.com>

guile-oauth is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 3 of the License, or (at your
option) any later version.

guile-oauth is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with guile-oauth. If not, see https://www.gnu.org/licenses/.
