Quick Start

Build a basic "Hello, World" Web API using Volga.

Prerequisites

Install Rust

If you haven't installed Rust yet, it is recommended to use the rustup. Here is the official guide where you can find how to do it.

Volga currently has a minimum supported Rust version (MSRV) of 1.80. Running rustup update will ensure you have the latest Rust version available.

Create an app

Create a new binary-based app:

cargo new hello-world
cd hello-world

Add the following dependencies in your Cargo.toml:

[dependencies]
volga = "0.6.3"
tokio = { version = "1", features = ["full"] }

Setup

Create your main application in main.rs:

use volga::{App, ok};

#[tokio::main]
async fn main() -> std::io::Result<()> {
    // Configure the server
    let mut app = App::new();

    // Example of a simple GET request handler
    app.map_get("/hello", || async {
        ok!("Hello, World!")
    });
    
    // Run the server
    app.run().await
}

Detailed Walkthrough

When the App struct is instantiated, it represents your API and by default binds it to http://localhost:7878:

let mut app = App::new();

Or if you need to bind it to another socket, you can use the bind() method like this:

// Binds the server to http://localhost:5000
let mut app = App::new().bind("localhost:5000");

Next, map a specific handler to a route. For instance, mapping our handler to GET /hello:

app.map_get("/hello", || {
    ok!("Hello, World!")
});

Ensure routes are mapped before you start the server with:

app.run().await

Testing the API

You can test your API using the curl command:

> curl -v "http://localhost:7878/hello"

Response expected:

* Host localhost:7878 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:7878...
* Connected to localhost (::1) port 7878
> GET /hello HTTP/1.1
> Host: localhost:7878
> User-Agent: curl/8.9.1
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 200 OK
< date: Sun, 6 Oct 2024 08:22:17 +0000
< server: Volga
< content-length: 12
< content-type: text/plain
<
* Connection #0 to host localhost left intact
Hello, World!

Blocking Example

Volga also supports building a Web API without explicitly depending on tokio, using the run_blocking() method.

This allows you to simplify your Cargo.toml dependencies:

[dependencies]
volga = "0.6.3"

Your main.rs might then look like this:

use volga::{App, ok};

fn main() {
    // Create the application
    let mut app = App::new();

    // Define a simple GET handler
    app.map_get("/hello", || async {
        ok!("Hello, World!")
    });

    // Run the server in blocking mode
    app.run_blocking()
}

Although the main function appears synchronous, the server still runs asynchronously under the hood using the tokio runtime.

You can also check out the full example here