Uses old Rust 2015
0.4.3 |
|
---|---|
0.4.2 |
|
0.4.0 |
|
0.3.0 |
|
0.1.1 |
|
#104 in #gitlab
29KB
549 lines
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 Response
s and JSON objects are response_future
and response_future_json
respectively.
Dependencies
~11–19MB
~279K SLoC