Expand description

A fully generated, opinionated API client library for GitHub.

docs.rs

API Details

GitHub’s v3 REST API.

API Terms of Service

Contact

License

Client Details

This client is generated from the GitHub OpenAPI specs based on API spec version 1.1.4. 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.37"

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.37", features = ["httpcache"] }

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

Here is an example:

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

#[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;

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

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.

Modules

Endpoints to manage GitHub Actions using the REST API.

Activity APIs provide access to notifications, subscriptions, and timelines.

Information for integrations and installations.

For performing functions related to authentication for the API.

Monitor charges and usage from Actions and Packages.

Rich interactions with checks run by your integrations.

Retrieve code scanning alerts from a repository.

Insight into codes of conduct for your communities.

List emojis available to use on GitHub.

Administer a GitHub enterprise.

View, modify your gists.

Raw Git functionality.

View gitignore templates.

http_cachehttpcache

Implements https://tools.ietf.org/html/rfc7232 Conditional Requests.

Owner or admin management of users interactions.

Interact with GitHub Issues.

View various OSS licenses.

Render Github flavored markdown.

Endpoints that give information about the API.

Move projects to or from GitHub.

Manage access of OAuth applications.

Interact with GitHub Orgs.

Manage packages for authenticated users and organizations.

Interact with GitHub Projects.

Interact with GitHub Pull Requests.

Check your current rate limit status.

Interact with reactions to various GitHub entities.

Interact with GitHub Repos.

Provisioning of GitHub organization membership for SCIM-enabled providers.

Look for stuff on GitHub.

Retrieve secret scanning alerts from a repository.

Interact with GitHub Teams.

The data types sent to and returned from the API client.

Interact with and view information about users and also current user.

Structs

Entrypoint for interacting with the API client.

Constants