https://github.com/luanzhu/roadrunner
A rust rest client based on hyper (https://github.com/hyperium/hyper).
https://github.com/luanzhu/roadrunner
hyper rest restclient rust
Last synced: 29 days ago
JSON representation
A rust rest client based on hyper (https://github.com/hyperium/hyper).
- Host: GitHub
- URL: https://github.com/luanzhu/roadrunner
- Owner: luanzhu
- License: mit
- Created: 2017-05-07T06:09:31.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2017-06-26T03:12:43.000Z (about 9 years ago)
- Last Synced: 2025-10-03T10:59:00.953Z (9 months ago)
- Topics: hyper, rest, restclient, rust
- Language: Rust
- Homepage:
- Size: 24.4 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Roadrunner (RR)
Roadrunner is a Rust Rest client based on [hyper project](https://github.com/hyperium/hyper) to
provide an user friendly interface for use.
The API interface is partially inspired by [unirest java library](http://unirest.io/java.html).
# Why?
I recently started to look at rust and noticed the choice of rest client in rust seemed to be
limited. Hyper client and some libcurl bindings I tried seem to be pretty low level to me.
Another big reason is that writing a library (no matter how small it is) seems to be a good
way to start a new language. :)
# Documentation
[Documentation generated by cargo doc](https://luanzhu.github.io/rust/doc/roadrunner/index.html).
# Example
(Besides the examples below, there is also a standalone example that uses RoadRunner client
to call themoviedb.org for upcoming movies, check it out: [https://github.com/luanzhu/movie_alert](https://github.com/luanzhu/movie_alert))
To run the example below, add RoadRunner to your `Cargo.toml`:
```toml
tokio-core = "0.1.6"
serde="1.0"
serde_json = "1.0"
serde_derive="1.0"
hyper = "0.11"
roadrunner = "0.1.1"
```
Then copy to your main.rs:
```rust
#[macro_use] extern crate serde_derive;
extern crate tokio_core;
extern crate serde_json;
extern crate hyper;
extern crate roadrunner;
// need both RestClient and RestClientMethods
use roadrunner::RestClient;
use roadrunner::RestClientMethods;
use hyper::StatusCode;
use serde_json::Value;
#[derive(Serialize, Deserialize, Debug, PartialEq)]
struct Address {
street: String,
city: String,
}
fn main () {
let mut core = tokio_core::reactor::Core::new().unwrap();
let original_typed = Address {
street: "135 College View Ave.".to_owned(),
city: "San Francisco".to_owned(),
};
let response = RestClient::post("http://mockbin.com/request")
.cookie("food", "bar")
.authorization_bearer("QWxhZGRpbjpvcGVuIHNlc2FtZQ".to_string())
.json_body_typed(&original_typed)
.execute_on(&mut core)
.unwrap();
println!("{:?}", response);
assert_eq!(*response.status(), StatusCode::Ok);
let json_value = response.content().as_value().unwrap();
assert_eq!(Value::String("application/json".to_owned()),
json_value["headers"]["content-type"]);
let data_str = json_value["postData"]["text"].as_str().unwrap();
println!("data_str : {:?}", data_str);
let response_typed: Address = serde_json::from_str(data_str).unwrap();
assert_eq!(original_typed, response_typed);
}
```
# Usage
## High level
High level API access is provided through [`RestClient`](https://luanzhu.github.io/rust/doc/roadrunner/struct.RestClient.html) and methods available in trait
[`RestClientMethods`](https://luanzhu.github.io/rust/doc/roadrunner/trait.RestClientMethods.html).
Please refer to tests in the tests folder for more example.
## Low level
For more control of request configuration, please use [`request_for_response`](https://luanzhu.github.io/rust/doc/roadrunner/fn.request_for_response.html).
The high level [`RestClient`](https://luanzhu.github.io/rust/doc/roadrunner/struct.RestClient.html) is
a thin layer on top of this function.
# Supported Methods
* GET
* POST
* PUT
* PATCH
* DELETE
* OPTIONS
# Run integration tests in tests folder?
To make tests self-contained, all integration tests are hitting local httpbin container (behind
a nginx container) in docker.
Please run the `start.sh` in the `docker-httpbin` folder to start two containers (one for httpbin and another one for nginx) locally
before you run integration tests.
**Warning**: because of [a recent regression
in httpbin](https://github.com/kennethreitz/httpbin/issues/340), httpbin.org cannot see the request
body transferred in chunks. Before the bug is fixed in httpbin, many tests will fail if they
hit httpbin.org directly.
## Add self-signed SSL cert into your CA
Hyper client relies on [rust-native-tls]((https://github.com/sfackler/rust-native-tls) to
handle https connections. However, there is no easy option to allow self-signed certs yet.
There is [an open issue regarding this](https://github.com/sfackler/rust-native-tls/issues/13).
(Why not use a hosted version of https endpoint for tests? You may ask. Well, I personally
would like to see what takes to work around this invalid certificate problem. I think it is
fairly common to have self-signed certificates in testing environments. To me, this extra
step serves as an exercise when I use this rest client or hyper client in future projects.)
As a result, the self-signed cert used in docker (docker-httpbin/config/localhost.cert) has to
be set to trusted (or added to trusted CA store). Otherwise, one test will fail.
# References
Some parts of implementations are based on ideas/examples from:
* [Hyper client example](https://github.com/hyperium/hyper/blob/master/examples/client.rs)
* [Get Data From A URL in Rust](http://hermanradtke.com/2015/09/21/get-data-from-a-url-rust.html)
# Related
* [hyper](https://github.com/hyperium/hyper)
* [tokio-curl](https://github.com/tokio-rs/tokio-curl)