A fully generated, opinionated API client library for GitHub.

This library is generated from the GitHub OpenAPI specs. This way it will remain up to date as features are added. The documentation for the crate is generated along with the code to make this library easy to use.

To install the library, add the following to your Cargo.toml file.

toml [dependencies] octorust = "0.1.3"

Basic example

Typical use will require intializing a Client. This requires a user agent string and set of auth::Credentials.

``` use octorust::{auth::Credentials, Client};

let github = Client::new( String::from("user-agent-name"), Credentials::Token( String::from("personal-access-token") ), ); ```

If you are a GitHub enterprise customer, you will want to create a client with the Client#host method.

Feature flags

httpcache

Github supports conditional HTTP requests using etags to checksum responses Experimental support for utilizing this to cache responses locally with the httpcache feature flag.

To enable this, add the following to your Cargo.toml file:

toml [dependencies] octorust = { version = "0.1.3", features = ["httpcache"] }

Then use the Client::custom constructor to provide a cache implementation.

Here is an example:

``` use octorust::{auth::Credentials, Client};

[cfg(feature = "httpcache")]

use octorust::http_cache::HttpCache;

[cfg(feature = "httpcache")]

let httpcache = HttpCache::inhome_dir();

[cfg(not(feature = "httpcache"))]

let github = Client::custom( "https://api.github.com", concat!(env!("CARGOPKGNAME"), "/", env!("CARGOPKGVERSION")), Credentials::Token( String::from("personal-access-token") ), reqwest::Client::builder().build().unwrap(), );

[cfg(feature = "httpcache")]

let github = Client::custom( "https://api.github.com", concat!(env!("CARGOPKGNAME"), "/", env!("CARGOPKGVERSION")), Credentials::Token( String::from("personal-access-token") ), reqwest::Client::builder().build().unwrap(), http_cache ); ```

Authenticating GitHub apps

You can also authenticate via a GitHub app.

Here is an example:

```rust use std::env;

use octorust::{Client, auth::{Credentials, InstallationTokenGenerator, JWTCredentials}};

[cfg(feature = "httpcache")]

use octorust::http_cache::FileBasedCache;

let appidstr = env::var("GHAPPID").unwrap(); let appid = appid_str.parse::().unwrap();

let appinstallationidstr = env::var("GHINSTALLATIONID").unwrap(); let appinstallationid = appinstallationidstr.parse::().unwrap();

let encodedprivatekey = env::var("GHPRIVATEKEY").unwrap(); let privatekey = base64::decode(encodedprivate_key).unwrap();

// Decode the key. let key = nompem::decodeblock(&private_key).unwrap();

// Get the JWT credentials. let jwt = JWTCredentials::new(app_id, key.data).unwrap();

// Create the HTTP cache.

[cfg(feature = "httpcache")]

let mut dir = dirs::home_dir().expect("Expected a home dir");

[cfg(feature = "httpcache")]

dir.push(".cache/github");

[cfg(feature = "httpcache")]

let http_cache = Box::new(FileBasedCache::new(dir));

let tokengenerator = InstallationTokenGenerator::new(appinstallation_id, jwt);

[cfg(not(feature = "httpcache"))]

let github = Client::custom( "https://api.github.com", concat!(env!("CARGOPKGNAME"), "/", env!("CARGOPKGVERSION")), Credentials::InstallationToken(token_generator), reqwest::Client::builder().build().unwrap(), );

[cfg(feature = "httpcache")]

let github = Client::custom( "https://api.github.com", concat!(env!("CARGOPKGNAME"), "/", env!("CARGOPKGVERSION")), Credentials::InstallationToken(tokengenerator), reqwest::Client::builder().build().unwrap(), httpcache, ); ```

Acknowledgements

Shout out to hubcaps for paving the way here. This extends that effort in a generated way so the library is always up to the date with the OpenAPI spec and no longer requires manual contributions to add new endpoints.