[][src]Crate octocrab

Octocrab: A modern, extensible GitHub API client.

Octocrab is an third party GitHub API client, allowing you to easily build your own GitHub integrations or bots. octocrab comes with two primary set of APIs for communicating with GitHub, a high level strongly typed semantic API, and a lower level HTTP API for extending behaviour.

Semantic API

The semantic API provides strong typing around GitHub's API, as well as a set of models that maps to GitHub's types. 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.
while let Some(page) = octocrab.get_page::<models::issues::Issue>(&page.next).await? {
    for issue in page {
        println!("{}", issue.title);
    }
}

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 that you have to now 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<Page<models::orgs::Organization>>;
}

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

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

Static API

octocrab also provides a statically reference count 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.
octocrab::instance();

Modules

actions

GitHub Actions

activity

Github Activity API

current

Get data about the currently authenticated user.

etag

Types for handling etags.

gitignore

The gitignore API

issues

The issue API.

licenses

Metadata about popular open source licenses and information about a project's license file.

markdown

The markdown API

models

Serde mappings from GitHub's JSON to structs.

orgs

The Organization API.

params

Common GitHub Parameter Types

pulls

The pull request API.

repos

The repositories API.

search

Using GitHub's search.

teams

The Teams API

Structs

GitHubError

An error returned from GitHub's API.

Octocrab

The GitHub API client.

OctocrabBuilder

A builder struct for Octocrab, allowing you to configure the client, such as using GitHub previews, the github instance, authentication, etc.

Page

A Page of GitHub results, with links to the next and previous page.

Enums

Error

An error that could have occurred while using crate::Octocrab.

Traits

FromResponse

A trait for mapping from a reqwest::Response to an another type.

Functions

format_media_type

Formats a media type from it's name into the full value for the Accept header.

format_preview

Formats a GitHub preview from it's name into the full value for the Accept header.

initialise

Initialises the static instance using the configuration set by builder.

instance

Returns a new instance of Octocrab. If it hasn't been previously initialised it returns a default instance with no authentication set.

map_github_error

Maps a GitHub error response into and Err() variant if the status is not a success.

Type Definitions

Result

A convenience type with a default error type of Error.