Crate hubcaps

Expand description

Hubcaps provides a set of building blocks for interacting with the GitHub API

§Examples

Typical use will require instantiation of a GitHub client. Which requires a user agent string and set of hubcaps::Credentials.

use hubcaps::{Credentials, Github};

let github = Github::new(
  String::from("user-agent-name"),
  Credentials::Token(
    String::from("personal-access-token")
  ),
);

GitHub enterprise customers will want to create a client with the Github#host method

Access to various services are provided via methods on instances of the Github type.

The convention for executing operations typically looks like github.repo(.., ..).service().operation(OperationOptions) where operation may be create, delete, etc.

Services and their types are packaged under their own module namespace. A service interface will provide access to operations and operations may access options types that define the various parameter options available for the operation. Most operation option types expose builder() methods for a builder oriented style of constructing options.

§Entity listings

Many of GitHub’s APIs return a collection of entities with a common interface for supporting pagination Hubcaps supports two types of interfaces for working with listings. list(...) interfaces return the first ( often enough ) list of entities. Alternatively for listings that require > 30 items you may wish to use the iter(..) variant which returns a futures::Stream over all entities in a paginated set.

§Errors

Operations typically result in a hubcaps::Future with an error type pinned to hubcaps::Error.

§Rate Limiting

A special note should be taken when accounting for GitHub’s API Rate Limiting A special case hubcaps::ErrorKind::RateLimit will be returned from api operations when the rate limit associated with credentials has been exhausted. This type will include a reset Duration to wait before making future requests.

This crate uses the log crate’s debug log interface to log x-rate-limit headers received from Github. If you are attempting to test your access patterns against GitHub’s rate limits, enable debug looking and look for “x-rate-limit” log patterns sourced from this crate

§Features

§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.hubcaps]
 version = "..."
 default-features = false
 features = ["default-tls","httpcache"]

Then use the Github::custom constructor to provide a cache implementation. See the conditional_requests example in this crates github repository for an example usage

Re-exports§

pub use crate::errors::Error;
pub use crate::errors::Result;

Modules§

activity: Activity interface
app: Labels interface
branches: Repo branches interface
checks: Checks interface
collaborators
comments: Comments interface
content: Content interface
deployments: Deployments interface
errors: Client errors
gists: Gists interface
git: Git interface
hooks: Hooks interface
issues: Issues interface
keys: Deploy keys interface
labels: Labels interface
membership: Organization Membership interface
notifications: Notifications interface
organizations: Organizations interface
pull_commits: Pull Commits interface
pulls: Pull requests interface
rate_limit: Rate Limit interface
releases: Releases interface
repo_commits: Repo Commits interface https://developer.github.com/v3/repos/commits/#get-a-single-commit
repositories: Repository interface
review_comments: Review comments interface
review_requests: Review requests interface
search: Search interface
stars: Stars interface
statuses: Statuses interface
teams: Teams interface
traffic: Traffic interface
users: Users interface
watching: Watching interface

Structs§

Github: Entry point interface for interacting with GitHub API
InstallationTokenGenerator: A caching token “generator” which contains JWT credentials.
JWTCredentials: JSON Web Token authentication mechanism

Enums§

AuthenticationConstraint: Controls what sort of authentication is required for this request
Credentials: Various forms of authentication credentials supported by GitHub
MediaType: GitHub defined Media types See this doc for more for more information
SortDirection: enum representation of Github list sorting options

Type Aliases§

Future: A type alias for Futures that may return hubcaps::Errors
Stream: A type alias for Streams that may result in hubcaps::Errors

Crate hubcapsCopy item path