Simple REST API

Build a small JSON API that manages a list of resources in memory, applying everything from structs to error handling.

StructsCollectionsError Handling

Overview

This project assumes the tiny_http = "0.12" crate for the HTTP server itself, plus serde = { version = "1", features = ["derive"] } and serde_json = "1" for JSON. tiny_http is a deliberately minimal, synchronous, thread-per-request HTTP library — it has no routing, no middleware, and no async runtime, which means every part of handling a request is code you write yourself in this tutorial rather than framework magic. That makes it a better teaching tool here than something like axum or actix-web, even though either of those would be a more typical production choice.

The one genuinely new idea in this project is *shared mutable state across threads*. Every earlier project in this course used a single-threaded loop where one TaskManager or ContactBook was only ever touched from main(). An HTTP server is different: tiny_http hands each incoming connection to its own OS thread, and every one of those threads needs to read and write the *same* in-memory list of resources. Rust will not let two threads hold a plain &mut Vec<Resource> to the same data at the same time — instead, this project wraps the data in Arc<Mutex<AppData>>, and you will see exactly what each of those two types is doing and why neither one alone would be enough.

What You'll Build

A Resource struct with #[derive(Serialize, Deserialize)] for automatic JSON conversion.
An AppData struct holding a Vec<Resource> and a next_id counter, shared via Arc<Mutex<AppData>>.
A tiny_http::Server accepting connections and dispatching each one onto its own thread.
GET /resources and GET /resources/:id handlers returning JSON.
A POST /resources handler that parses a JSON request body with serde_json.
A DELETE /resources/:id handler and a small router matching method + path.

Prerequisites

Everything from the earlier projects in this course — structs, Result, ownership, and HashMap/Vec.
Basic familiarity with HTTP — methods (GET/POST/DELETE), status codes, and JSON request/response bodies.
Traits at a conceptual level — what #[derive(...)] does and why a struct needs Serialize/Deserialize to convert to/from JSON.
Arc<T> and Mutex<T> — that both exist specifically to let multiple threads safely share one piece of data.
Closures — std::thread::spawn(move || { ... }) and what the move keyword does to the closure's captures.

Project Structure

Create the project with cargo new resource_api and add the three dependencies above to Cargo.toml. Everything lives in src/main.rs: the Resource and NewResource structs and their derives, the AppData struct and the SharedState type alias built around it, one handler function per HTTP method (list_resources, get_resource, create_resource, delete_resource), a small handle_request() router, and main(), which binds the server and spawns one thread per incoming request.

Every handler function takes &SharedState (a reference to the Arc<Mutex<AppData>>, not an owned copy of it) and returns a String of JSON — handlers never write directly to the HTTP response, they just produce a body, and handle_request() is the only place that actually calls request.respond(...). That separation is what makes each handler trivially testable on its own, independent of any real HTTP connection.

Step 1: Model the Resource With Serde

#[derive(Serialize, Deserialize)] is what lets serde_json::to_string(&resource) and serde_json::from_str::<Resource>(&body) work without writing any conversion code by hand — the derive macro generates it at compile time based on the struct's fields. NewResource is a second, smaller struct with only name and description: the client sending a POST body should never be able to specify their own id, since assigning ids is the server's job, the same rule TaskManager and Bank followed in earlier projects.

use serde::{Deserialize, Serialize};

// Serialize lets serde_json::to_string(&resource) work; Deserialize lets
// serde_json::from_str::<Resource>(json) work. Both are generated by the
// derive macro at compile time -- no hand-written JSON code needed.
#[derive(Debug, Clone, Serialize, Deserialize)]
struct Resource {
    id: u32,
    name: String,
    description: String,
}

// Only name/description are accepted from the client. There is no id field
// here on purpose: the server assigns ids itself in create_resource() (Step 5),
// so a client can never request or overwrite a specific id.
#[derive(Debug, Deserialize)]
struct NewResource {
    name: String,
    description: String,
}

Step 2: Define Shared Application State

AppData bundles the resource list and the id counter into one struct so both are protected by a single Mutex — using two separate Mutexes (one for the Vec, one for the counter) would let one thread observe them briefly out of sync with each other. Arc (Atomically Reference Counted) is what allows every worker thread to hold its own handle to the *same* AppData — cloning an Arc bumps a shared, thread-safe reference count and is cheap; it never copies the AppData itself. Mutex is what makes it safe for more than one thread to touch that shared data at all: only the thread currently holding the lock may read or write it, and every other thread calling .lock() blocks until that lock is released.

use std::sync::{Arc, Mutex};

// Bundled into one struct (not two separate fields behind two separate
// Mutexes) so that assigning an id and pushing the new Resource always
// happen while holding a single, consistent lock -- see create_resource()
// in Step 5.
struct AppData {
    resources: Vec<Resource>,
    next_id: u32,
}

impl AppData {
    fn new() -> AppData {
        AppData { resources: Vec::new(), next_id: 1 }
    }
}

// Arc lets many threads each hold a cheap, cloned handle to the SAME
// AppData. Mutex ensures only one thread at a time can actually read or
// write through that handle. Neither alone would be enough: Arc without
// Mutex allows concurrent access with no protection; Mutex without Arc
// can't be shared across threads in the first place.
type SharedState = Arc<Mutex<AppData>>;

Step 3: Start the HTTP Server and Accept Connections

Server::http(...) binds a TCP listener and returns a tiny_http::Server; server.incoming_requests() is a blocking iterator that yields one Request per connection. Arc::clone(&state) inside the loop is the key line: it does not clone AppData, it clones the Arc handle pointing at it, which is why passing shared state into a new thread is cheap even though the underlying Vec<Resource> might be large. The move keyword on the closure is required because the spawned thread must own its copy of state and request for as long as it runs, potentially after main()'s loop has moved on to accept the next connection.

use tiny_http::Server;

fn main() {
    let server = Server::http("127.0.0.1:8080").expect("failed to bind to port 8080");
    println!("Listening on http://127.0.0.1:8080");

    let state: SharedState = Arc::new(Mutex::new(AppData::new()));

    for request in server.incoming_requests() {   // Blocks here until a new connection arrives
        let state = Arc::clone(&state);   // Cheap: bumps a reference count, does NOT copy AppData itself
        std::thread::spawn(move || {        // move: this thread must own its `state` and `request` handles
            handle_request(request, state);
        });
    }
}

Step 4: Handle GET Requests

state.lock() returns a LockResult<MutexGuard<AppData>>; .unwrap() on it only panics if some other thread already panicked while holding the lock (a "poisoned" mutex), which is treated here as an unrecoverable programming error, not a normal failure to handle gracefully. While the returned MutexGuard is alive, this thread — and only this thread — may read or write the AppData it wraps; the guard releases the lock automatically when it goes out of scope at the end of the function.

fn list_resources(state: &SharedState) -> String {
    let data = state.lock().unwrap();   // Blocks until no other thread holds the lock; releases it when `data` drops
    serde_json::to_string(&data.resources).unwrap_or_else(|_| "[]".to_string())
}

fn get_resource(state: &SharedState, id_str: &str) -> String {
    let id: u32 = match id_str.parse() {
        Ok(n) => n,
        Err(_) => return json_error("invalid id"),
    };

    let data = state.lock().unwrap();
    match data.resources.iter().find(|r| r.id == id) {   // Borrowed search, same pattern as ContactBook::find()
        Some(resource) => serde_json::to_string(resource).unwrap_or_else(|_| json_error("serialization failed")),
        None => json_error("resource not found"),
    }
}

// Small shared helper: every handler below returns its error bodies through
// this one function so the JSON error shape stays consistent everywhere.
fn json_error(message: &str) -> String {
    format!("{{\"error\":\"{message}\"}}")
}

Step 5: Handle POST Requests

create_resource() reads the raw request body into a String with request.as_reader().read_to_string(...), then hands that text to serde_json::from_str::<NewResource>(...), which either succeeds with a NewResource or fails with a serde_json::Error if the body is not valid JSON or is missing a required field. Assigning id and inserting the new Resource both happen while the same MutexGuard (data) is held, which is exactly why AppData bundled resources and next_id into one struct behind one Mutex back in Step 2 — no other thread can observe an id being handed out without the matching resource existing yet.

use std::io::Read;

fn create_resource(request: &mut tiny_http::Request, state: &SharedState) -> String {
    let mut body = String::new();
    if request.as_reader().read_to_string(&mut body).is_err() {
        return json_error("could not read request body");
    }

    let new_resource: NewResource = match serde_json::from_str(&body) {
        Ok(nr) => nr,
        Err(_) => return json_error("invalid JSON body"),
    };

    let mut data = state.lock().unwrap();   // Mutable guard: this thread now has exclusive access to AppData
    let id = data.next_id;
    let resource = Resource { id, name: new_resource.name, description: new_resource.description };
    data.resources.push(resource.clone());   // Push a clone; the original `resource` is still needed for the response below
    data.next_id += 1;                        // Same guard, same lock -- no other thread can hand out this id meanwhile

    serde_json::to_string(&resource).unwrap_or_else(|_| json_error("serialization failed"))
}

Step 6: Handle DELETE Requests

delete_resource() reuses the same retain() pattern the CLI Task Manager project used to delete-by-predicate: keep every resource whose id does not match, and check whether the length actually shrank to know whether anything was removed. The whole operation — reading resources.len(), calling retain(), comparing lengths again — happens under one lock acquisition, so no other thread can insert or delete a resource in the middle of it.

fn delete_resource(state: &SharedState, id_str: &str) -> String {
    let id: u32 = match id_str.parse() {
        Ok(n) => n,
        Err(_) => return json_error("invalid id"),
    };

    let mut data = state.lock().unwrap();
    let before = data.resources.len();
    data.resources.retain(|r| r.id != id);   // Same delete-by-predicate pattern as TaskManager::remove_task()
    if data.resources.len() < before {
        "{\"status\":\"deleted\"}".to_string()
    } else {
        json_error("resource not found")
    }
}

Step 7: Wire Up the Request Router

handle_request() splits the URL path on / into segments and matches on (method, segments) together, so the routing table reads almost exactly like the table below it. Rust's slice patterns (["resources"], ["resources", id]) let a match compare both the *shape* (how many segments) and the *content* (a literal segment like "resources") of a Vec<&str> in one arm, which is what makes this small hand-written router readable without a routing crate.

Method	Path	Description
GET	/resources	List every resource currently in memory
GET	/resources/:id	Fetch a single resource by id
POST	/resources	Create a resource from a JSON body
DELETE	/resources/:id	Delete a resource by id

use tiny_http::{Header, Method, Request, Response};

fn handle_request(mut request: Request, state: SharedState) {
    let method = request.method().clone();
    let url = request.url().to_string();
    let segments: Vec<&str> = url.trim_matches('/').split('/').collect();

    // Matching (method, segments.as_slice()) together lets one match express
    // the whole routing table -- method AND path shape AND path content,
    // all in a single readable arm per route.
    let body = match (method, segments.as_slice()) {
        (Method::Get, ["resources"]) => list_resources(&state),
        (Method::Get, ["resources", id]) => get_resource(&state, id),
        (Method::Post, ["resources"]) => create_resource(&mut request, &state),
        (Method::Delete, ["resources", id]) => delete_resource(&state, id),
        _ => json_error("not found"),
    };

    let content_type = Header::from_bytes(&b"Content-Type"[..], &b"application/json"[..]).unwrap();
    let response = Response::from_string(body).with_header(content_type);

    // Ignoring the Result here: a failed write means the client already
    // disconnected, and there is nothing more useful this thread can do
    // about that before it exits.
    let _ = request.respond(response);
}

Complete Code

Here is the full program assembled in the correct order. Add tiny_http = "0.12", serde = { version = "1", features = ["derive"] }, and serde_json = "1" to Cargo.toml, save this as src/main.rs, and run with cargo run.

use serde::{Deserialize, Serialize};
use std::io::Read;
use std::sync::{Arc, Mutex};
use tiny_http::{Header, Method, Request, Response, Server};

#[derive(Debug, Clone, Serialize, Deserialize)]
struct Resource {
    id: u32,
    name: String,
    description: String,
}

#[derive(Debug, Deserialize)]
struct NewResource {
    name: String,
    description: String,
}

struct AppData {
    resources: Vec<Resource>,
    next_id: u32,
}

impl AppData {
    fn new() -> AppData {
        AppData { resources: Vec::new(), next_id: 1 }
    }
}

type SharedState = Arc<Mutex<AppData>>;

fn json_error(message: &str) -> String {
    format!("{{\"error\":\"{message}\"}}")
}

fn list_resources(state: &SharedState) -> String {
    let data = state.lock().unwrap();
    serde_json::to_string(&data.resources).unwrap_or_else(|_| "[]".to_string())
}

fn get_resource(state: &SharedState, id_str: &str) -> String {
    let id: u32 = match id_str.parse() {
        Ok(n) => n,
        Err(_) => return json_error("invalid id"),
    };

    let data = state.lock().unwrap();
    match data.resources.iter().find(|r| r.id == id) {
        Some(resource) => serde_json::to_string(resource).unwrap_or_else(|_| json_error("serialization failed")),
        None => json_error("resource not found"),
    }
}

fn create_resource(request: &mut Request, state: &SharedState) -> String {
    let mut body = String::new();
    if request.as_reader().read_to_string(&mut body).is_err() {
        return json_error("could not read request body");
    }

    let new_resource: NewResource = match serde_json::from_str(&body) {
        Ok(nr) => nr,
        Err(_) => return json_error("invalid JSON body"),
    };

    let mut data = state.lock().unwrap();
    let id = data.next_id;
    let resource = Resource { id, name: new_resource.name, description: new_resource.description };
    data.resources.push(resource.clone());
    data.next_id += 1;

    serde_json::to_string(&resource).unwrap_or_else(|_| json_error("serialization failed"))
}

fn delete_resource(state: &SharedState, id_str: &str) -> String {
    let id: u32 = match id_str.parse() {
        Ok(n) => n,
        Err(_) => return json_error("invalid id"),
    };

    let mut data = state.lock().unwrap();
    let before = data.resources.len();
    data.resources.retain(|r| r.id != id);
    if data.resources.len() < before {
        "{\"status\":\"deleted\"}".to_string()
    } else {
        json_error("resource not found")
    }
}

fn handle_request(mut request: Request, state: SharedState) {
    let method = request.method().clone();
    let url = request.url().to_string();
    let segments: Vec<&str> = url.trim_matches('/').split('/').collect();

    let body = match (method, segments.as_slice()) {
        (Method::Get, ["resources"]) => list_resources(&state),
        (Method::Get, ["resources", id]) => get_resource(&state, id),
        (Method::Post, ["resources"]) => create_resource(&mut request, &state),
        (Method::Delete, ["resources", id]) => delete_resource(&state, id),
        _ => json_error("not found"),
    };

    let content_type = Header::from_bytes(&b"Content-Type"[..], &b"application/json"[..]).unwrap();
    let response = Response::from_string(body).with_header(content_type);
    let _ = request.respond(response);
}

fn main() {
    let server = Server::http("127.0.0.1:8080").expect("failed to bind to port 8080");
    println!("Listening on http://127.0.0.1:8080");

    let state: SharedState = Arc::new(Mutex::new(AppData::new()));

    for request in server.incoming_requests() {
        let state = Arc::clone(&state);
        std::thread::spawn(move || {
            handle_request(request, state);
        });
    }
}

Sample Run

Click Run to see what this code prints.

Extend This Project

Add a PUT /resources/:id handler that fully replaces an existing resource's fields.
Return proper HTTP status codes (201 Created, 404 Not Found, 400 Bad Request) instead of always responding 200 OK with a JSON error body.
Persist AppData to a JSON file on every write with serde_json::to_writer, and load it back in main() on startup.
Add basic query-string filtering, e.g. GET /resources?name=Widget, by parsing request.url() beyond the path.
Swap tiny_http for axum and compare how much of the routing, JSON parsing, and shared-state code this tutorial wrote by hand a framework provides for you.

Summary

You built a small JSON API where serde handles the mechanical work of converting between Resource structs and JSON text, and Arc<Mutex<AppData>> is what makes it safe for many threads — one per incoming connection — to share and mutate the same in-memory resource list without corrupting it. The Arc clones a cheap handle, the Mutex enforces that only one thread touches the underlying data at a time, and every handler you wrote stayed a plain function taking &SharedState and returning a String, independent of any particular HTTP request. That is the same combination of ownership discipline and small, composable functions this whole course has been building toward, now applied to genuinely concurrent code.