anterofit 0.0.3

Wrap REST APIs with Rust traits using macros

Crate anterofit [] [src]

Wrap REST calls with Rust traits.

#[macro_use] extern crate anterofit;

service! {
    /// Trait wrapping `` API.
    pub trait MyService {
        /// Get the version of this API.
        fn api_version(&self) -> String {

        /// Register a user with the API.
        fn register(&self, username: &str, password: &str) {
            fields! {
                username, password

Important Types

Service Traits

Created with the service!{} macro as shown above, service traits encompass the actual request submission and response parsing. Each service trait is automatically implemented for Adapter, and is object-safe by default, so you can use generic bounds or trait object coercion to narrow the scope:

fn print_api_version(service: &MyService) {
    // This completes synchronously, blocking until the request is complete.
    let api_version = service.api_version().exec_here().unwrap();
    println!("API version: {}", api_version);

fn register_user<S: MyService>(service: &S, username: &str, password: &str) {
    // By default, this will complete asynchronously.
    service.register(username, password)
        // exec() queues the request on the executor,
        // and ignore() silences the `unused_result` lint for `Call`.

    // This function returns immediately; all the work is done on the executor.

For more details, see the service!{} macro.


Built via Adapter::builder(), this is the starting point for all requests. It encompasses five core components, and one very important property:

  • The Executor is responsible for taking prepared requests and executing them. Since Anterofit is primarily designed to be asynchronous, the executor should submit jobs to be completed in the background. Several executors are provided in the executor module, but a sane default for low-volume asynchronous requests is provided automatically.

  • The Interceptor is a non-essential but endlessly useful component which can modify request parameters before they are submitted. This currently encompasses modifying the request URL and adding or overwriting HTTP headers. If your app requires some sort of API key or authentication header, you can add an interceptor to your adapter to automatically include the appropriate credentials with each request:

use anterofit::{Adapter, Url};
use anterofit::net::intercept::AddHeader;
use anterofit::net::header::{Headers, Authorization, Bearer};

let adapter = Adapter::builder()
    .interceptor(AddHeader(Authorization (
        Bearer {
            token: "asdf1234hjkl5678".to_string()

Interceptor is also implemented for closures of the kind Fn(&mut anterofit::net::request::RequestHead), but common operations are implemented as types in the anterofit::net::interceptor module. You can also chain interceptors together, or call box_interceptor() to transform it to Box<Interceptor> if you need to name the full type of Adapter.

  • The Serializer is responsible for taking a strongly typed request body and converting it to something that can be read into the HTTP stream, such as JSON or a raw byte sequence.

  • Conversely, the Deserializer is responsible for taking a response body in some predetermined format, such as JSON or XML, and reading out a strongly typed value.

If you just want JSON serialization and deserialization and don't care about the details, use the serialize_json() method of your adapter builder to set the serializer and deserializer simultaneously.

  • The Client (hyper::client::Client) is responsible for managing proxies, DNS resolution, and bootstrapping connections. A default instance will be constructed automatically if one is not provided, but you can configure your own instance to tweak some low-level stuff like timeouts or to use a particular proxy.

  • Finally, the base_url, if provided, is automatically prepended to every request URL. This would generally be the protocol, domain and perhaps a path prefix, while request URLs can be standalone paths. That way you can easily swap between, for example, testing and production endpoints implementing the same REST API:

use anterofit::{Adapter, Url};

let adapter = Adapter::builder()

register_user(&adapter, "username", "password");

let adapter = Adapter::builder()

register_user(&adapter, "username", "password");


This type wraps the return value of every service trait method. Unlike in Retrofit (v1; v2 uses this pattern now, but is more verbose), where the request is determined to be synchronous or asynchronous at the service method declaration site, Request gives the power over this choice to the caller so that no change to the trait is needed to change the execution context:

fn print_api_version(service: &MyService) {
        // This closure will be called with the `String` value on the executor
        .on_complete(|api_version| println!("API version: {}", api_version))
        // We don't care about the result since it's `()` anyway.


Returned by Request::exec(), this type is a pollable Future which will yield the result of the request when it is ready. If there was an error in constructing the request, the result will be available immediately. Call shadows Future::poll() and Future::wait() with inherent methods that do not require the use of types from the futures crate, so you have a choice over whether you want to use futures in your app or not.


pub extern crate hyper;
pub use error::Error;
pub use net::body::RawBody;
pub use net::request::Request;



Assorted error types and helper functions used by this crate.


Types which can take a boxed closure and execute it, preferably in the background.


Shorthands for various MIME types.


Anterofit's HTTP client framework, built on Hyper.


Types used to serialize and deserialize request and response bodies, respectively.



Serialize the given value as the request body.


Serialize a series of key-value pairs as the request body.


Serialize a series of fields as the request body (form-encode them).


Use in a service method body to perform an arbitrary transformation on the builder.


A field value that resolves to a path on the filesystem.


Append a series of query pairs to the URL of the request.


Define a service trait whose methods make HTTP requests.


A field value for anything that is Read + Send + 'static.


Use in a service body to access the builder without consuming it.



The starting point of all Anterofit requests.


A parsed URL record.



Implemented by Adapter. Mainly used to simplify generics.

Type Definitions


The result type for this crate; used frequently in public APIs.