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
.
extern crate hubcaps;
extern crate hyper;
use hubcaps::{Credentials, Github};
fn main() {
let github = Github::new(
String::from("user-agent-name"),
Credentials::Token(
String::from("personal-access-token")
),
);
}
Github enterprise users 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 = ["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