Crate octorust 

A fully generated, opinionated API client library for GitHub.

API Details

GitHub’s v3 REST API.

API Terms of Service

Contact

name	url
Support	https://support.github.com/contact?tags=rest-api

License

name	url
MIT	https://spdx.org/licenses/MIT

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.10.0"

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_override 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.10.0", 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(
    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(
    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;
use base64::{Engine, engine::general_purpose::STANDARD};

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 = STANDARD.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(
    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(
    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

actions

Endpoints to manage GitHub Actions using the REST API.

activity

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

apps

Information for integrations and installations.

auth

For performing functions related to authentication for the API.

billing

Monitor charges and usage from Actions and Packages.

checks

Rich interactions with checks run by your integrations.

code_scanning

Retrieve code scanning alerts from a repository.

codes_of_conduct

Insight into codes of conduct for your communities.

emojis

List emojis available to use on GitHub.

enterprise_admin

Administer a GitHub enterprise.

gists

View, modify your gists.

git

Raw Git functionality.

gitignore

View gitignore templates.

http_cachehttpcache

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

interactions

Owner or admin management of users interactions.

issues

Interact with GitHub Issues.

licenses

View various OSS licenses.

markdown

Render Github flavored markdown.

meta

Endpoints that give information about the API.

migrations

Move projects to or from GitHub.

oauth_authorizations

Manage access of OAuth applications.

orgs

Interact with GitHub Orgs.

packages

Manage packages for authenticated users and organizations.

projects

Interact with GitHub Projects.

pulls

Interact with GitHub Pull Requests.

rate_limit

Check your current rate limit status.

reactions

Interact with reactions to various GitHub entities.

repos

Interact with GitHub Repos.

scim

Provisioning of GitHub organization membership for SCIM-enabled providers.

search

Look for stuff on GitHub.

secret_scanning

Retrieve secret scanning alerts from a repository.

teams

Interact with GitHub Teams.

types

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

users

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

Structs

Client

Entrypoint for interacting with the API client.

HeaderMap

A set of HTTP headers

Response

RootDefaultServer

StatusCode

An HTTP status code (status-code in RFC 9110 et al.).

Enums

ClientError

Errors returned by the client

Constants

FALLBACK_HOST