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:

This example is not tested
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::intercept module. You can also chain interceptors together; they will be called in declaration order.

  • 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, where the request is determined to be synchronous or asynchronous at the service method declaration site^1, Request gives the power over this choice to the caller so that no change to the trait is needed to change the execution context:

This example is not tested
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.

^1 : Retrofit v1 established synchronicity at the declaration site; v2 follows the same pattern as Anterofit, but the two were developed independently.


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 provides alternative methods wrapping Future::poll() and Future::wait() without external types 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).


Allows the inside expression to set a body on a request which doesn't regularly take one.


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


Create a meta-service trait which combines the listed service traits.


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.


Create an implementation of UnsizeService for the given service trait.


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



The starting point of all Anterofit requests.


A builder for Adapter. Call Adapter::builder() to get an instance.


A mutator for modifying the Interceptor of an Adapter.


A parsed URL record.



Used by Anterofit's various APIs.


Unsizeable service trait. Used with Adapter::arc_service().

Type Definitions


A shorthand for an adapter with JSON serialization enabled.


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