#date #client #github #api #code #documentation #github-api #place #opinionated

nightly octorust

A fully generated & opinionated API client for the GitHub API

17 releases

new 0.1.16 Jul 27, 2021
0.1.15 Jul 21, 2021

#99 in Development tools

Download history 89/week @ 2021-07-08 687/week @ 2021-07-15 577/week @ 2021-07-22

292 downloads per month

MIT license

2.5MB
47K SLoC

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.

[dependencies]
octorust = "0.1.16"

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:

[dependencies]
octorust = { version = "0.1.16", 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 http_cache = HttpCache::in_home_dir();

#[cfg(not(feature = "httpcache"))]
let github = Client::custom(
    "https://api.github.com",
    concat!(env!("CARGO_PKG_NAME"), "/", env!("CARGO_PKG_VERSION")),
    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!("CARGO_PKG_NAME"), "/", env!("CARGO_PKG_VERSION")),
    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:

use std::env;

use octorust::{Client, auth::{Credentials, InstallationTokenGenerator, JWTCredentials}};
#[cfg(feature = "httpcache")]
use octorust::http_cache::FileBasedCache;

let app_id_str = env::var("GH_APP_ID").unwrap();
let app_id = app_id_str.parse::<u64>().unwrap();

let app_installation_id_str = env::var("GH_INSTALLATION_ID").unwrap();
let app_installation_id = app_installation_id_str.parse::<u64>().unwrap();

let encoded_private_key = env::var("GH_PRIVATE_KEY").unwrap();
let private_key = base64::decode(encoded_private_key).unwrap();

// Decode the key.
let key = nom_pem::decode_block(&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 token_generator = InstallationTokenGenerator::new(app_installation_id, jwt);

#[cfg(not(feature = "httpcache"))]
let github = Client::custom(
    "https://api.github.com",
    concat!(env!("CARGO_PKG_NAME"), "/", env!("CARGO_PKG_VERSION")),
    Credentials::InstallationToken(token_generator),
    reqwest::Client::builder().build().unwrap(),
);

#[cfg(feature = "httpcache")]
let github = Client::custom(
    "https://api.github.com",
    concat!(env!("CARGO_PKG_NAME"), "/", env!("CARGO_PKG_VERSION")),
    Credentials::InstallationToken(token_generator),
    reqwest::Client::builder().build().unwrap(),
    http_cache,
);

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.

Dependencies

~12–16MB
~425K SLoC