Getting Started

To begin, ensure you have Rust and Cargo installed. You can install Actix Web via Cargo with the following command:

cargo new actix_rest_api
cd actix_rest_api
cargo add actix-web
cargo add serde serde_json

This example will create a basic API for managing a list of users. It will support endpoints for listing all users, retrieving a user by ID, and adding a new user.

Project Setup and Dependencies

Your Cargo.toml will look like this after adding the dependencies:

[package]
name = "actix_rest_api"
version = "0.1.0"
edition = "2021"

[dependencies]
actix-web = "4.3"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

Next, create a basic main.rs entry point and define a User struct:

use actix_web::{web, App, HttpServer, Responder, HttpResponse, get, post};
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug)]
struct User {
    id: u32,
    name: String,
    email: String,
}

async fn index() -> impl Responder {
    HttpResponse::Ok().body("Welcome to the Actix Web API!")
}

#[get("/users")]
async fn get_users() -> impl Responder {
    let users = vec![
        User { id: 1, name: "Alice".to_string(), email: "[email protected]".to_string() },
        User { id: 2, name: "Bob".to_string(), email: "[email protected]".to_string() },
    ];
    HttpResponse::Ok().json(users)
}

#[get("/users/{id}")]
async fn get_user(path: web::Path<u32>) -> impl Responder {
    let id = path.into_inner();
    let user = User { id, name: "John Doe".to_string(), email: "[email protected]".to_string() };
    HttpResponse::Ok().json(user)
}

#[post("/users")]
async fn create_user(user: web::Json<User>) -> impl Responder {
    println!("Creating user: {:?}", user);
    HttpResponse::Created().json(user.0)
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            .service(index)
            .service(get_users)
            .service(get_user)
            .service(create_user)
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

Key Concepts and Best Practices

ConceptDescription
Responder traitRequired for returning HTTP responses from handler functions.
web::PathUsed to extract path parameters from the URL.
web::JsonUsed to deserialize JSON payloads from the request body.
#[derive(Serialize, Deserialize)]Enables serialization and deserialization of structs for JSON.
#[get("/route")] and #[post("/route")]Macro-based route handlers for defining HTTP methods.

Actix Web provides a clean and expressive way to define routes and manage request handling. To maintain clean code, it is recommended to separate route handlers into modules or use dependency injection for shared services like a database connection or logger.

Advanced Features and Structuring

For larger applications, structuring your code into modules and using dependency injection can greatly improve maintainability. Here’s an example of how to extract the user handling logic into a module:

Create a new file src/user.rs:

use actix_web::{web, HttpResponse, Responder, get, post};
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug)]
pub struct User {
    pub id: u32,
    pub name: String,
    pub email: String,
}

pub fn get_users() -> impl Responder {
    let users = vec![
        User { id: 1, name: "Alice".to_string(), email: "[email protected]".to_string() },
        User { id: 2, name: "Bob".to_string(), email: "[email protected]".to_string() },
    ];
    HttpResponse::Ok().json(users)
}

#[get("/users/{id}")]
pub async fn get_user(path: web::Path<u32>) -> impl Responder {
    let id = path.into_inner();
    let user = User { id, name: "John Doe".to_string(), email: "[email protected]".to_string() };
    HttpResponse::Ok().json(user)
}

#[post("/users")]
pub async fn create_user(user: web::Json<User>) -> impl Responder {
    println!("Creating user: {:?}", user);
    HttpResponse::Created().json(user.0)
}

Update main.rs to use the module:

mod user;
use user::{get_users, get_user, create_user};

async fn index() -> impl Responder {
    HttpResponse::Ok().body("Welcome to the Actix Web API!")
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            .service(index)
            .service(get_users)
            .service(get_user)
            .service(create_user)
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

This modular approach allows for better code organization and makes it easier to scale the application with more features and endpoints.

Error Handling and Middleware

Actix Web supports middleware for logging, authentication, and error handling. Here is an example of a simple logging middleware:

use actix_web::{middleware, web, App, HttpServer, HttpResponse, Responder};

async fn index() -> impl Responder {
    HttpResponse::Ok().body("Welcome to the Actix Web API!")
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            .wrap(middleware::Logger::default())
            .service(index)
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

The Logger middleware logs incoming requests and responses, which is invaluable for debugging and performance analysis.

Learn more with useful resources