HappyGAPI

A Clojure library for calling Google APIs; gsheets, drive, bigquery and so on.

Rationale

HappyGAPI generates source code that defines functions for calling GAPI, so you don't have to! The discovery based approach is inspired by clj-gapi.

The advantages of generating source code are:

1. Navigate to source
2. See all available resources and methods
3. Clear exceptions on failure

HappyGAPI accepts data instead of an objects.

Usage

Add the dependency to the project file:

Require happygapi.<api>.<resource> in the code:

(ns my.ns
  (:require [happygapi.sheets.spreadsheets :as gsheets]
            [happy.oauth2 :as oauth2]))

Call the api:

(gsheets/get$ (oauth2/auth!) {:spreadsheetId "xyz"})

(gsheets/values-batchUpdate$ (oauth2/auth!)
                             {:spreadsheetId spreadsheet-id}
                             {:valueInputOption "USER_ENTERED"
                              :data             [{:range  "Sheet1"
                                                  :values [[1 2 3]
                                                           [4 5 6]]}]})

Functions are generated according to this pattern:

(happygapi.<api>.<resource>/<?subresource(s)>-<method> auth params ?body)

Where auth is a map to apply to the request, params and body align with REST documentation. For example see batchUpdate.

The json-schema files are written as edn to resources. I plan to add json-schema validation to the body soon.

Authorization

The auth argument can be one of:

{}                                                   ; anonymous
{:query-params {"key" api-key}}                      ; api-key
{:headers {"Authorization" (str "Bearer " token)}}   ; oauth2 token

The auth argument is merged into the request. You can specify additional request options if you want to.

The happy.oauth2 namespace provides a convenient way to authorize requests. It needs access to secret.json which can be downloaded from the Google Console. Do not add this file to source control, keep it secured. Follow the "Getting started" Google API instructions to create an App.

Calling (auth!) will start a singleton oauth2 listener. If you prefer to start one with non-default configuration see (start! config). If you prefer to use a system graph instead of a singleton, see (start*). If you prefer to run your own oauth2 listener, pass in auth from some other source.

Contributing

Issues, pull requests, and suggestions are welcome.

Building

The api namespaces can be generated by running happy.lion/-main

lein run

Testing

To run the test you need to download secret.json from the Google console.

lein test

License

Copyright © 2020 Timothy Pratley

This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at http://www.eclipse.org/legal/epl-2.0.

This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version, with the GNU Classpath Exception which is available at https://www.gnu.org/software/classpath/license.html.