teatime

A library to make implementing REST API tools easier in Rust

Documentation

Reference and usage documentation is here.

Contibuting

For contribution guidelines, please click here

lib.rs:

teatime

A wrapper library for simplifying REST API implementations

Motivation

When writing tools in Rust that talk with REST API endpoints, there is often some boilerplate code needed when using hyper for HTTP API requests. Much of this has to do with writing code to handle futures and finding where some of the modification methods live for things like headers and request body, something that is not always transparent to programmers coming from an imperative language background. This library abstracts away some of these details and allows the user to either ignore the details of future handling or optionally drop down to the future level, exposing a builder pattern for HTTP requests for API flows. Additionally helpful actions like JSON API autopagination and HTTP body to JSON conversions are already implemented.

Reference implementations

There are three reference implementations included, one for Sensu, one for Gitlab, and one for Vault. This is probably the best example of common patterns for defining to required methods that do not have default implementations.

Using teatime

The bulk of teatime is driven through the HttpClient, ApiClient and JsonApiClient traits. There are additional data structures to help with type safety when dealing with REST APIs that have a very loose type model.

See the documentation for ApiClient and JsonApiClient as well as all of data structures defined in lib.rs as these will outline parameter types, return types and required implementation bits.

Traditional request-response flows vs. future-based flows

Once the ApiClient trait is implemented, an API can either be made through the request method for a hyper Response type or request_json for automatic conversion of the response body to JSON.

For cases where futures are desirable, there are two method calls for the request-response flow. The first is request_future. This will return a future which can be left as is while other work is done. This is the same for both Response and JSON flows. The resolution functions that resolve to Responses and JSON objects are response_future and response_future_json respectively.