patron

A wrapper around the hyper.rs library to allow for targeted clients to specific remote APIs. This library should be useful on it's own or as a building block for specific remote API wrappers.

The Interface

Exports

We want to give out an owned std::sync::Arc wrapped client so that the user can utilize the client between threads if ncessary.

```rust pub type Client = std::sync::Arc;

```

Create an HTTP Star Wars API client.

```rust struct Person { name: String, birthyear: String, eyecolor: String, height: String, mass: String, }

let client = try!(patron::from_str("http://swapi.co/api") .build() );

let hansolo: Person = try!client.get("/people/14") .send() .andthen(|res| res.deserialize()) ); ```

Creating an HTTPs GitHub Api client with an OAuth2 token.

```rust use patron;

let client: patron::Client = try!( patron::fromstr("https://api.github.com") .setoauth_token("0b79bab50daca910b000d4f1a2b675d604257e42") .build() ); ```

Creating an HTTPs GitHub Api client using query based tokens.

```rust use patron;

let client: patron::Client = try!( patron::fromstr("https://api.github.com") .addqueryparam("clientid", "ABCDEFGHIKLMNOP") .addqueryparam("client_secret", "QRSTUVWXYZABCDE") .build() ); ```

Creating an HTTP client for CouchDB.

```rust use patron;

let url: patron::Url = try!( patron::Url::new() .setscheme(patron::Scheme::Http) .sethost('localhost') .set_port(5984) .build() );

let client: patron::Client = try!( patron::fromurl(url) .addpath("somedatabase") .basic_auth("anna", "secret") .build() ); ```

Example usage for ArangoDB

THIS IS NOT FULLY IMPLEMENTED, LIES ABOUND! ```rust use serde_json; use patron;

[derive(Debug, Deserialize)]

struct AuthRes { jwt: String, mustchangepassword: bool, }

// Generally this would be built from some configuration object. let mut url = patron::url::Url::new() url.setscheme(patron::Scheme::Http) url.sethost("localhost") url.set_port(8529)

let auth: AuthRes = try!( patron::Request::new(url) .post("/open/auth") .addbodyparam("username", "root") .addbody_param("password", "password") .send() );

let mydbclient: patron::Client = try!( patron::fromurl(url) .setoauthtoken(auth.jwt) .addpath("/db/mydb/") .build() );

[derive(Debug, Deserialize)]

struct Version { version: String, server: String, }

let version: Version = try!(client.get("/_api/version").send());

[derive(Debug, Deserialize, Serialize)]

struct NewDoc { #[serde(rename = "key")] key: String, #[serde(rename = "id")] id: String, #[serde(rename = "_rev")] revision: String, }

let newdoc: NewDoc = try!( client.post("/api/demo") .addbodyparam("message", serdejson::tovalue("").unwrap()) .addquery_param("waitForSync", "true") .send() );

[derive(Debug, Deserialize, Serialize)]

struct Document { #[serde(rename = "key")] key: String, #[serde(rename = "id")] id: String, #[serde(rename = "_rev")] revision: String, message: Option }

let mut hello: Document = try!( client.get("/api/document/demo/") .addpath(newdoc.id) .send() );

hello.message = Some("Hello, World!");

[derive(Debug, Deserialize, Serialize)]

struct UpdateRes { #[serde(rename = "key")] key: String, #[serde(rename = "id")] id: String, #[serde(rename = "rev")] revision: String, #[serde(rename = "oldRev")] previous_revision: String, }

let res: UpdateRes = try!( client.put("/api/document/demo") .addpath(hello.id) .setbody(hello) .send() ); ```

Design

Response Objects: Fetch API

Notes

• Should the client be passed into the send method?
• I would like to only have one representation of a request configuration instead of the current 2.
• A more functional style design?
• I like how the fetch API returns a response object with the ability to retrieve the Body in different formats. How can this be presented along with a nice Result based interface? rust client.get('/foo') .send() .unwrap() .json() send() will return a Response object which you can call .json(). The .json() method will return a Result<serde_json::Value, Error>