HappyAPI

A middleware oriented oauth2 client for webservices, and code generation for discovery documents.

See HappyGAPI for calling Google APIs; gsheets, drive, bigquery, and so on. HappyGAPI is generated by HappyAPI.

Features

• OAuth2
• Middleware for flexibly constructing your own request stack
• Pluggable dependency detection for http and json
• Code generation
• Sync/Async

Rationale

Large datasets and extensive functionality are available to us through web APIs, but calling these services is often a study in incidental complexity. Happy GAPI simplifies access to the wide range of Google services that include AI models, OCR, translation, Gmail, and Youtube. It generates discoverable, developer-friendly functions that wrap web APIs. It also supports reuse of common helpful operations across multiple dependencies, including important non-functional aspects like authentication, logging, metrics, metering, error handling.

Many interesting webservices need OAuth2 to access them. Oauth2 works "out of the box" for standalone, and with minimal configuration in a web server.

Exposing the key functionality through composable middleware allows users flexibility to do things differently, and reuse parts when accessing APIs from another provider.

Client libraries are often over-specific (see death by specificity). We can do better with maps but we still have to know the shape of requests and tediously research documentation. HappyAPI emphasizes discoverability without objects by generating code and documentation from an API discovery document. HappyAPI generates functions (as code, not macros) for calling API endpoints, so that your editor can help you:

1. Autocomplete; See all available resources and methods
2. Help documentation; The function doc-strings contain a description, a link to online docs, and example inputs (TODO: is this true?)
3. Arity checking; Required parameters are function args
4. Informative exceptions on failure

The discovery of GAPIs was inspired by clj-gapi. See Google API discovery: https://developers.google.com/discovery/v1/getting_started

This approach should work well with other discovery documents, hopefully AWS will be added soon.

Usage

Hopefully you'll find the generated libraries like HappyGAPI useful and wont need to use HappyAPI directly. If for whatever reason you would prefer to use HappyAPI, add the dependency to your project file:

Require happy.oauth2.client in the code:

(ns my.ns
  (:require [happy.oauth2.client :as client]))

Authorization

To participate in oauth2 you need to fetch and store tokens.

To create an app in the Google Console, follow Setting up OAuth 2.0. When setting up the app credentials, add http://localhost/redirect to the authorized redirect URIs, and add yourself as a test user.

There are two methods for obtaining a token:

• User redirects, which prompt a user to authorize your app. Download the secret.json from the Google Console. Do not add this file to source control, keep it secured. This method is suitable if you want users to grant your app access to their data.
• Service account private key (suitable for server to server). Create a Service account and download a service.json key file. Do not add this file to source control, keep it secured. This method is suitable for automated jobs.

By default, it tries to read secret.json or service.json from disk in the current directory. You can pass in configuration map of the same shape instead. happy.oauth2-credentials stores tokens on disk. If you want to use HappyAPI in a web app, you should instead store and fetch tokens from your database.

The happy.oauth2.capture-redirect namespace provides a listener to capture a code when the user is redirected to your site from the oauth2 provider. If you use it, you will need to include ring as a dependency. Web applications should instead define a route to capture the code.

Retries

HappyAPI leaves retries up to the consuming application. However, if you are doing many requests, it is likely you will want to retry failed requests, as failures can happen for a variety of availability reasons. See the "again" library.

Contributing

Issues, pull requests, and suggestions are welcome.

Updating

Building pulls down the latest schema. You can build it yourself if this library has not been updated in a while. Please email me if you'd like me to push an updated version.

Building

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

lein run

Testing

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

lein test

Deploying

lein release clojars

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.