Need help with octocrab?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

XAMPPRocky
309 Stars 51 Forks Other 230 Commits 23 Opened issues

Description

A modern, extensible GitHub API Client for Rust.

Services available

!
?

Need anything else?

Contributors list

Octocrab: A modern, extensible GitHub API client.

Rust crates.io Help Wanted Lines Of Code Documentation

Octocrab is a third party GitHub API client, allowing you to easily build your own GitHub integrations or bots in Rust.

Octocrab
comes with two primary sets of APIs for communicating with GitHub, a high level strongly typed semantic API, and a lower level HTTP API for extending behaviour.

Cargo.toml

octocrab = "0.9"

Semantic API

The semantic API provides strong typing around GitHub's API, a set of

models
that maps to GitHub's types, and
auth
functions that are useful for GitHub apps. Currently, the following modules are available.

Getting a Pull Request

// Get pull request #404 from `octocrab/repo`.
let issue = octocrab::instance().pulls("octocrab", "repo").get(404).await?;

All methods with multiple optional parameters are built as

Builder
structs, allowing you to easily specify parameters.

Listing issues

use octocrab::{models, params};

let octocrab = octocrab::instance(); // Returns the first page of all issues. let page = octocrab.issues("octocrab", "repo") .list() // Optional Parameters .creator("octocrab") .state(params::State::All) .per_page(50) .send() .await?;

// Go through every page of issues. Warning: There's no rate limiting so // be careful. let mut next_page = page.next; while let Some(page) = octocrab.get_page::<:issue>(&next_page).await? { next_page = page.next; for issue in page { println!("{}", issue.title); } } </:issue>

HTTP API

The typed API currently doesn't cover all of GitHub's API at this time, and even if it did GitHub is in active development and this library will likely always be somewhat behind GitHub at some points in time. However that shouldn't mean that in order to use those features, you have to fork or replace

octocrab
with your own solution.

Instead

octocrab
exposes a suite of HTTP methods allowing you to easily extend
Octocrab
's existing behaviour. Using these HTTP methods allows you to keep using the same authentication and configuration, while having control over the request and response. There is a method for each HTTP method,
get
,
post
,
patch
,
put
,
delete
, all of which accept a relative route and a optional body.
let user: octocrab::models::User = octocrab::instance()
    .get("/user", None::)
    .await?;

Each of the HTTP methods expects a body, formats the URL with the base URL, and errors if GitHub doesn't return a successful status, but this isn't always desired when working with GitHub's API, sometimes you need to check the response status or headers. As such there are companion methods

_get
,
_post
, etc. that perform no additional pre or post-processing to the request.
let octocrab = octocrab::instance();
let response =  octocrab
    ._get("https://api.github.com/organizations", None::)
    .await?;

// You can also use Octocrab::absolute_url if you want to still to go to // the same base. let response = octocrab ._get(octocrab.absolute_url("/organizations")?, None::) .await?;

You can use the those HTTP methods to easily create your own extensions to

Octocrab
's typed API. (Requires
async_trait
).
use octocrab::{Octocrab, Page, Result, models};

#[async_trait::async_trait] trait OrganisationExt { async fn list_every_organisation(&self) -> Result>; }

#[async_trait::async_trait] impl OrganisationExt for Octocrab { async fn list_every_organisation(&self) -> Result> { self.get("/organizations", None::).await } }

You can also easily access new properties that aren't available in the current models using

serde
.
#[derive(Deserialize)]
struct RepositoryWithVisibility {
    #[serde(flatten)]
    inner: octocrab::models::Repository,
    visibility: String,
}

let my_repo = octocrab::instance() .get::("https://api.github.com/repos/XAMPPRocky/octocrab", None::) .await?;

Static API

Octocrab
also provides a statically reference counted version of its API, allowing you to easily plug it into existing systems without worrying about having to integrate and pass around the client.
// Initialises the static instance with your configuration and returns an
// instance of the client.
octocrab::initialise(octocrab::Octocrab::builder());
// Gets a instance of `Octocrab` from the static API. If you call this
// without first calling `octocrab::initialise` a default client will be
// initialised and returned instead.
let octocrab = octocrab::instance();

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.