README.md

Roctogen: Rust Client Library for GitHub v3 API

Roctogen is a Rust library generated from the GitHub REST API OpenAPI specification. providing comprehensive support for the GitHub v3 API. It offers flexible support for both synchronous and asynchronous HTTP clients, including WebAssembly compatibility. You can choose between multiple client libraries via Cargo features, or integrate your own HTTP client handling by extending the adapter subsytem:

• reqwest: Enables asynchronous requests using the Reqwest client
• ureq: Provides synchronous requests with the Ureq client

Installation

To include Roctogen in your project, add it to your Cargo.toml:

[dependencies]
roctogen = "*"

Documentation

• API docs.
• Endpoints.

Supported endpoints:

Roctogen supports a wide range of GitHub API endpoints, including:

• Meta
• Issues
• Licenses
• Reactions
• Activity
• Projects
• Orgs
• Users
• Apps
• RateLimit
• Repos
• SecretScanning
• SecurityAdvisories
• Packages
• Search
• Classroom
• Teams
• Oidc
• Markdown
• Actions
• Migrations
• Gists
• CodeSecurity
• DependencyGraph
• Copilot
• Dependabot
• CodesOfConduct
• Pulls
• Gitignore
• Git
• CodeScanning
• Checks
• Billing
• Interactions
• Codespaces
• Emojis

For a full list of supported endpoints, refer to the API documentation.

Usage

Here's a basic example demonstrating how to use Roctogen:

use roctogen::api::{self, repos};
use roctogen::adapters::client;
use roctogen::auth::Auth;

let auth = Auth::None;
let client = client(&auth).expect("Cannot create new client");
let per_page = api::PerPage::new(10);

let mut params: repos::ReposListCommitsParams = per_page.as_ref().into();
params = params.author("fussybeaver").page(2);

repos::new(&client).list_commits("fussybeaver", "bollard", Some(params));

Asynchronous Requests

For async support, use the _async suffix for method calls. These are available with the reqwest, or WebAssembly targets.

Webassembly

Roctogen can be compiled to WebAssembly using wasm-pack or by directly targeting wasm32-unknown-unknown:

$ wasm-pack build

$ cargo build --target wasm32-unknown-unknown

Client adapters

Roctogen supports multiple HTTP clients, or you can write your own. Enable the desired client using Cargo features:

Reqwest

Compile with Reqwest support using the reqwest feature:

$ cargo build --features reqwest

Ureq

Compile with Ureq support using the ureq feature:

$ cargo build --features ureq

Custom Client Adapters

It's possible to write your own adapter, by extending roctogen::adapters::Client. This allows you to handle rate limiting and pagination - an example of extending the base adapter is available in the example min-req-adapter.

Generating the API

Roctogen's code is largely generated from the GitHub REST API specification using the Swagger OpenAPI generator (version 3). Building the API requires the Java-based mvn tool with JDK 8 installed:

$ mvn -D org.slf4j.simpleLogger.defaultLogLevel=info clean compiler:compile generate-resources

Testing

Roctogen supports both WebAssembly and synchronous test environments. Be aware that some tests perform real HTTP requests to the GitHub API unless mocked.

• WebAssembly Tests:

$ wasm-pack test --firefox --headless

• ** Synchronous Tests:

$ cargo test --features isahc,mercy,squirrel-girl,inertia,starfox --target x86_64-unknown-linux-gnu -- --nocapture

To avoid GitHub's API rate limits during testing, you can use WireMock to mock the API locally. Run the following to start WireMock, and run the tests with the --mock feature:

$ docker run -d --name wiremock -p 8080:8080 -v $PWD/tests/stubs:/home/wiremock
rodolpheche/wiremock
$ cargo test --feature mock,ureq

Regenerate the wiremock stubs

If the GitHub API changes, you can regenerate the WireMock stubs:

$ docker run -d --name wiremock -p 8080:8080 -v $PWD/tests/stubs:/home/wiremock -u (id -u):(id -g) rodolpheche/wiremock --verbose --proxy-all="https://api.github.com" --record-mappings

License: Apache-2.0