Vamo, a rest api friendly client

Continuing our series of blog posts about deboa ecosystem, we will now cover Vamo, a rest api client built on top of deboa.

Despite existing http clients written in rust, deboa comes with this friendly companion crate. Vamo is a very straightforward way to setup your client once with a base url, allowing you issue your requests after by just specifying the path of resource to be requested.

Installing

In order to start using vamo in your project, please add vamo into your project with following command:

cargo add vamo

Initializing client

Initialize vamo client is easy as initialize a deboa client, let's check out the example below.

Example

use vamo::Vamo;

let vamo = Vamo::new("https://api.example.com")?;

Sending requests

Now that we have vamo client initialized, you can start issuing your requests, don't mind to give full url anymore, just the resource path and you are done.

Example

use vamo::Vamo;

let vamo = Vamo::new("https://api.example.com")?;
let response = vamo
    .get("/users")?
    .send()
    .await?;

Request trait

Request trait is a experimental feature of vamo crate, with Request trait, you can easily turn any rust struct into a kind self contained request object to be sent over vamo.

Example

use deboa::{client::serde::RequestBody, Result};
use vamo::{Vamo, resource::{Resource, ResourceMethod}};
use deboa_extras::http::serde::json::JsonBody;
use serde::Serialize;

#[derive(Serialize)]
struct Post {
    id: u64,
    title: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    body: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    user_id: Option<u64>,
}

impl Resource for Post {
    fn id(&self) -> String {
        self.id.to_string()
    }

    fn name(&self) -> &str {
        "posts"
    }

    fn body_type(&self) -> impl RequestBody {
        JsonBody
    }
}

let mut vamo = Vamo::new("https://api.example.com")?;
// Assuming Post is a Resource
let mut post = Post {
     id: 1,
     title: "Some title".to_string(),
     body: "Some body".to_string(),
     user_id: 1,
};
let response = vamo.create(&mut post)?.send().await?;

Please note that you don't need to implement Resource trait manually, in order to make this happen, please check section below.

Final thoughts

As we can see, it is faily simple make requests with vamo, and to make this task even more simplier, a Request trait has been introduced to make every happen straight from your structs. I stronly invite you to also give a try on vamo-macros, which can simply generate a implementation of Request trait for your struct by just annotating your struct with #[derive(Resource)].

You can find vamo under deboa repository at https://github.com/ararog/deboa, or under creates.io at https://crates.io/crates/deboa.

A complete documentation is also available at https://docs.rs/vamo/latest/vamo/.