DEV Community: Seven

How to Build a REST API in Zig (Using Spider Web Framework)

Seven — Mon, 09 Mar 2026 20:58:18 +0000

In this tutorial, I will cover the basics of the Spider Web Framework by creating a simple REST API with full CRUD operations.

In this article:

Step 1: Project Setup
Step 2: Basic Server
Step 3: PostgreSQL Setup
Step 4: Connect Spider to PostgreSQL
Step 5: CRUD Endpoints

Prerequisites

Make sure you have the following installed:

Zig 0.16.0-dev.2676+ — ziglang.org/download
Docker — docker.com
libpq (PostgreSQL client library)

On Arch Linux:

pacman -S postgresql-libs

For other distributions (Debian, Ubuntu, Fedora, etc.), install the equivalent package — usually libpq-dev or postgresql-devel.

Verify the installation:

pkg-config --exists libpq && echo "ok"

Step 1: Project Setup

Create a new project and fetch Spider:

mkdir mma-api && cd mma-api
zig init
zig fetch --save git+https://github.com/llllOllOOll/spider

After running zig fetch, a new entry named .spider will be added to your build.zig.zon under .dependencies. Let's check it to make sure everything looks correct:

// build.zig.zon
.dependencies = .{
    .spider = .{
        .url = "git+https://github.com/llllOllOOll/spider#f79bfab69d1c99fa552583bd2cc627d34f894260",
        .hash = "spider-0.3.0-RIctlSneAQAo31OblO8nx0AZLGT0-d5qjb4aAjdzp4lP",
    },
},

Now update build.zig to add Spider as a dependency and link against libpq:

const spider_dep = b.dependency("spider", .{ .target = target });
const exe = b.addExecutable(.{
    .name = "mma_api",
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
        .link_libc = true, // required for libpq
        .imports = &.{
            .{ .name = "spider", .module = spider_dep.module("spider") },
        },
    }),
});
exe.root_module.linkSystemLibrary("pq", .{});
b.installArtifact(exe);

Step 2: Basic Server

Replace src/main.zig with our first handler:

const std = @import("std");
const spider = @import("spider");

fn pingHandler(alloc: std.mem.Allocator, _: *spider.Request) !spider.Response {
    return spider.Response.json(alloc, .{ .msg = "pong" });
}

pub fn main(init: std.process.Init) !void {
    const arena: std.mem.Allocator = init.arena.allocator();
    const io = init.io;
    const server = try spider.Spider.init(arena, io, "0.0.0.0", 8080);
    defer server.deinit();
    server
        .get("/ping", pingHandler)
        .listen() catch |err| return err;
}

Build, run, and test it:

zig build run
curl http://localhost:8080/ping
# {"msg":"pong"}

As you can see, it's very easy to get a server running with Spider! To stop it, press Ctrl+\.

Step 3: PostgreSQL Setup

We'll use Docker to run PostgreSQL locally. Create a docker-compose.yml:

services:
  db:
    container_name: mma_db
    image: postgres:17
    environment:
      POSTGRES_USER: spider
      POSTGRES_PASSWORD: spider
      POSTGRES_DB: mma_db
    ports:
      - "5432:5432"
    volumes:
      - mma_data:/var/lib/postgresql/data

volumes:
  mma_data:

If port 5432 is already in use, change it to another port (e.g. 5433:5432) and update your .env accordingly.

Start the container:

docker compose up -d

Connect and create the table:

docker exec -it mma_db psql -U spider -d mma_db

CREATE TABLE fighters (
    id         SERIAL PRIMARY KEY,
    name       VARCHAR(100) NOT NULL,
    nickname   VARCHAR(100),
    division   VARCHAR(50)  NOT NULL,
    record     VARCHAR(20)  NOT NULL
);

INSERT INTO fighters (name, nickname, division, record) VALUES
    ('Jon Jones',            'Bones',               'Heavyweight',       '27-1-0'),
    ('Khabib Nurmagomedov',  'The Eagle',           'Lightweight',       '29-0-0'),
    ('Anderson Silva',       'The Spider',          'Middleweight',      '34-11-0'),
    ('Georges St-Pierre',    'GSP',                 'Welterweight',      '26-2-0'),
    ('Fedor Emelianenko',    'The Last Emperor',    'Heavyweight',       '40-6-0'),
    ('Conor McGregor',       'The Notorious',       'Lightweight',       '22-6-0'),
    ('Demetrious Johnson',   'Mighty Mouse',        'Flyweight',         '30-4-1'),
    ('Chuck Liddell',        'The Iceman',          'Light Heavyweight', '21-9-0'),
    ('Randy Couture',        'The Natural',         'Heavyweight',       '19-11-0'),
    ('Royce Gracie',         'The Legend',          'Open Weight',       '15-2-3'),
    ('Daniel Cormier',       'DC',                  'Heavyweight',       '22-3-0'),
    ('Stipe Miocic',         'Stone Cold',          'Heavyweight',       '20-4-0'),
    ('Israel Adesanya',      'The Last Stylebender','Middleweight',      '24-3-0'),
    ('Kamaru Usman',         'The Nigerian Nightmare','Welterweight',    '20-3-0'),
    ('Tony Ferguson',        'El Cucuy',            'Lightweight',       '25-9-0'),
    ('BJ Penn',              'The Prodigy',         'Lightweight',       '16-14-2'),
    ('Cris Cyborg',          'Cyborg',              'Featherweight',     '26-2-1'),
    ('Amanda Nunes',         'The Lioness',         'Bantamweight',      '23-5-0'),
    ('Jose Aldo',            'Junior',              'Featherweight',     '31-8-0'),
    ('Valentina Shevchenko', 'Bullet',              'Flyweight',         '23-4-1');

SELECT * FROM fighters;

Pretty cool — there are all our fighters!

Step 4: Connect Spider to PostgreSQL

Create a .env file at the root of your project:

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=spider
POSTGRES_PASSWORD=spider
POSTGRES_DB=mma_db

Add .env to your .gitignore — never commit credentials.

Step 5: CRUD Endpoints

Now let's build the full CRUD API. Here's the complete src/main.zig:

const std = @import("std");
const spider = @import("spider");
const db = spider.pg;

const Fighter = struct {
    id:       i32,
    name:     []const u8,
    nickname: []const u8,
    division: []const u8,
    record:   []const u8,
};

const NewFighter = struct {
    name:     []const u8,
    nickname: []const u8,
    division: []const u8,
    record:   []const u8,
};

fn pingHandler(alc: std.mem.Allocator, _: *spider.Request) !spider.Response {
    return spider.Response.json(alc, .{ .msg = "pong" });
}

fn getFighters(alc: std.mem.Allocator, _: *spider.Request) !spider.Response {
    var result = try db.query("SELECT id, name, nickname, division, record FROM fighters");
    defer result.deinit();
    const fighters = try result.mapAll(Fighter, alc);
    return spider.Response.json(alc, fighters);
}

fn getFighter(alc: std.mem.Allocator, req: *spider.Request) !spider.Response {
    const id = req.param("id") orelse return spider.Response.json(alc, .{ .err = "missing id" });
    var result = try db.queryParams(
        "SELECT id, name, nickname, division, record FROM fighters WHERE id = $1",
        &[_][]const u8{id},
    );
    defer result.deinit();
    const fighters = try result.mapAll(Fighter, alc);
    if (fighters.len == 0) return spider.Response.json(alc, .{ .err = "fighter not found" });
    return spider.Response.json(alc, fighters[0]);
}

fn createFighter(alc: std.mem.Allocator, req: *spider.Request) !spider.Response {
    const body = try req.bindJson(alc, NewFighter);
    _ = try db.queryParams(
        "INSERT INTO fighters (name, nickname, division, record) VALUES ($1, $2, $3, $4)",
        &[_][]const u8{ body.name, body.nickname, body.division, body.record },
    );
    return spider.Response.json(alc, .{ .msg = "fighter created" });
}

fn updateFighter(alc: std.mem.Allocator, req: *spider.Request) !spider.Response {
    const id = req.param("id") orelse return spider.Response.json(alc, .{ .err = "missing id" });
    const body = try req.bindJson(alc, NewFighter);
    _ = try db.queryParams(
        "UPDATE fighters SET name=$1, nickname=$2, division=$3, record=$4 WHERE id=$5",
        &[_][]const u8{ body.name, body.nickname, body.division, body.record, id },
    );
    return spider.Response.json(alc, .{ .msg = "fighter updated" });
}

fn deleteFighter(alc: std.mem.Allocator, req: *spider.Request) !spider.Response {
    const id = req.param("id") orelse return spider.Response.json(alc, .{ .err = "missing id" });
    _ = try db.queryParams(
        "DELETE FROM fighters WHERE id=$1",
        &[_][]const u8{id},
    );
    return spider.Response.json(alc, .{ .msg = "fighter deleted" });
}

pub fn main(init: std.process.Init) !void {
    const arena: std.mem.Allocator = init.arena.allocator();
    const io = init.io;

    spider.loadEnv(arena, ".env") catch {};
    try db.init(arena, .{});
    defer db.deinit();

    const server = try spider.Spider.init(arena, io, "0.0.0.0", 8080);
    defer server.deinit();

    server
        .get("/ping", pingHandler)
        .get("/fighters", getFighters)
        .get("/fighters/:id", getFighter)
        .post("/fighters", createFighter)
        .put("/fighters/:id", updateFighter)
        .delete("/fighters/:id", deleteFighter)
        .listen() catch |err| return err;
}

Build and run:

zig build run

Test all endpoints:

# List all fighters
curl http://localhost:8080/fighters

# Get a single fighter
curl http://localhost:8080/fighters/1
# {"id":1,"name":"Jon Jones","nickname":"Bones","division":"Heavyweight","record":"27-1-0"}

# Create a fighter
curl -X POST http://localhost:8080/fighters \
  -H "Content-Type: application/json" \
  -d '{"name":"Mirko Cro Cop","nickname":"Cro Cop","division":"Heavyweight","record":"38-11-2"}'
# {"msg":"fighter created"}

# Update a fighter
curl -X PUT http://localhost:8080/fighters/21 \
  -H "Content-Type: application/json" \
  -d '{"name":"Mirko Cro Cop","nickname":"Cro Cop","division":"Heavyweight","record":"40-11-2"}'
# {"msg":"fighter updated"}

# Delete a fighter
curl -X DELETE http://localhost:8080/fighters/21
# {"msg":"fighter deleted"}

Conclusion

And that's it! We have a fully working REST API in Zig using the Spider Web Framework. Let's recap what we built:

Method	Endpoint	Description
GET	`/fighters`	List all fighters
GET	`/fighters/:id`	Get a fighter by ID
POST	`/fighters`	Create a fighter
PUT	`/fighters/:id`	Update a fighter
DELETE	`/fighters/:id`	Delete a fighter

In just a few lines of Zig, we connected to a PostgreSQL database, mapped query results directly to structs using mapAll, and served a clean JSON API — with no boilerplate.

Spider is still in early development, but already powerful enough to build real-world APIs. If you want to learn more, check out the official documentation at spiderme.org and give it a ⭐ on GitHub — it really helps the project grow!

If you have any questions or feedback, feel free to leave a comment below.

Happy coding! 🕷️

Written by Seven — GitHub · X · 7b37b3@gmail.com

Parallel Programming in Zig: Threads, Shared Memory, and Synchronization

Seven — Thu, 26 Feb 2026 21:36:38 +0000

Introduction

This post continues my exploration of low-level programming and the Zig language. Today, we will explore the fundamental concepts of parallel programming. We'll start by defining what threads are, then move on to spawning them in Zig, and finally, we'll see how to handle shared memory safely using synchronization primitives.

Step 1: The Basic Process

Every program runs as a process with at least one thread. Let's start by creating a simple task and running it in our main function. At this stage, everything is sequential.

const std = @import("std");

pub fn main() !void {
    std.debug.print("Starting main thread...\n", .{});
    task(1);
    std.debug.print("Finished main thread.\n", .{});
}

fn task(id: usize) void {
    std.debug.print("task {} is running\n", .{id});
    var ts = std.posix.timespec{ .sec = 1, .nsec = 0 };
    _ = std.posix.system.nanosleep(&ts, &ts);
}

Output:
Starting main thread...
task 1 is running
Finished main thread.

Step 2: Spawning Your First Thread

Now, let's use std.Thread.spawn to run the task on a separate path of execution. We use thread.join() to tell the main thread to wait for the worker to finish.

Note that in Zig 0.16, main can receive a std.process.Init argument, which gives us access to std.Io — used here to measure elapsed time with std.Io.Clock.

const std = @import("std");

pub fn main(init: std.process.Init) !void {
    const start = std.Io.Clock.now(.real, init.io);
    const thread = try std.Thread.spawn(.{}, task, .{1});
    thread.join(); // This blocks the main thread until the task is done
    const end = std.Io.Clock.now(.real, init.io);
    const duration = start.durationTo(end);
    std.debug.print("Time: {}ms\n", .{duration.toMilliseconds()});
}

fn task(id: usize) void {
    std.debug.print("Task {} is running thread: {} \n", .{ id, std.Thread.getCurrentId() });
    var ts = std.posix.timespec{ .sec = 1, .nsec = 0 };
    _ = std.posix.system.nanosleep(&ts, &ts);
}

Output:
Task 1 is running thread: 1134137
Time: 1000ms

Step 3: Running in Parallel

To use your CPU cores effectively, we can spawn multiple threads. By storing them in an array and joining them after spawning all of them, they all work at the same time.

Notice that 4 threads each sleeping for 1 second still complete in ~1000ms total — they truly run in parallel.

const std = @import("std");

pub fn main(init: std.process.Init) !void {
    const start = std.Io.Clock.now(.real, init.io);
    var threads: [4]std.Thread = undefined;
    for (&threads, 0..) |*t, i| {
        t.* = try std.Thread.spawn(.{}, task, .{i});
    }
    for (threads) |t| t.join();
    const end = std.Io.Clock.now(.real, init.io);
    const duration = start.durationTo(end);
    std.debug.print("Time: {}ms\n", .{duration.toMilliseconds()});
}

fn task(id: usize) void {
    std.debug.print("Task {} is running thread: {} \n", .{ id, std.Thread.getCurrentId() });
    var ts = std.posix.timespec{ .sec = 1, .nsec = 0 };
    _ = std.posix.system.nanosleep(&ts, &ts);
}

Output:
Task 0 is running thread: 1134350
Task 1 is running thread: 1134351
Task 2 is running thread: 1134352
Task 3 is running thread: 1134353
Time: 1000ms

Step 4: The Shared Memory Problem (Race Condition)

Threads share the same memory space. If multiple threads try to update the same variable at once, they will overwrite each other's changes, causing a race condition — the final result will be inconsistent and unpredictable.

const std = @import("std");

// This will produce inconsistent results!
pub fn main() !void {
    var arr = [_]i32{ 0, 0, 0 };
    var threads: [5]std.Thread = undefined;
    for (&threads) |*t| {
        t.* = try std.Thread.spawn(.{}, task, .{&arr});
    }
    for (threads) |t| t.join();
    std.debug.print("Result: {any}\n", .{arr});
}

fn task(arr: *[3]i32) void {
    for (0..100000) |_| {
        for (0..3) |j| arr[j] += 1;
    }
}

Output:
Result: { 311264, 289236, 273695 }

The expected result would be { 500000, 500000, 500000 } (5 threads × 100000 iterations), but we get something different — and it changes on every run. That is the race condition in action.

Step 5: Fixing it with Mutex and Defer

To fix the bug, we use a Mutex to lock the critical section — the block of code that accesses shared data. Only one thread can hold the lock at a time, so the others wait their turn.

In Zig 0.16, the mutex is std.Io.Mutex and its lock/unlock methods require passing the std.Io handle. We also pass io down to the task function for this reason.

Notice that we lock and unlock inside the loop, wrapping only the minimal critical section. Locking outside the loop would force threads to run one at a time for their entire duration, eliminating any parallelism benefit.

We also use defer mutex.unlock(io) immediately after the lock. This ensures the lock is always released when the block exits, even if an error occurs.

const std = @import("std");

pub fn main(init: std.process.Init) !void {
    var arr = [_]i32{ 0, 0, 0 };
    var mutex = std.Io.Mutex.init;
    var threads: [5]std.Thread = undefined;
    for (&threads) |*t| {
        t.* = try std.Thread.spawn(.{}, task, .{ &arr, &mutex, init.io });
    }
    for (threads) |t| t.join();
    std.debug.print("Result: {any}\n", .{arr});
}

fn task(arr: *[3]i32, mutex: *std.Io.Mutex, io: std.Io) !void {
    for (0..100000) |_| {
        {
            try mutex.lock(io);
            defer mutex.unlock(io); // released at the end of this block
            for (0..3) |j| arr[j] += 1;
        }
    }
}

Output:
Result: { 500000, 500000, 500000 }

Now the result is consistent and correct on every run.

Tip: For simple numeric operations on a single variable, Zig also provides std.atomic.Value, which can be more efficient than a Mutex since it avoids the overhead of locking entirely.

Conclusion

Parallel programming is a powerful tool for building high-performance software, but it requires a solid understanding of how threads interact. We've seen how easy it is to spawn threads in Zig, but also how quickly shared memory can lead to subtle bugs. By using tools like std.Io.Mutex — and understanding where to apply them — we can protect our data and ensure our programs remain correct and reliable as they scale across multiple CPU cores.

References

Sources & Further Reading

Contact

Feel free to reach out or follow my work:

Written with 0.16.0-dev.2565+684032671 — All code tested and verified.

My journey with code. Today threads: Threaded vs Evented

Seven — Tue, 24 Feb 2026 22:41:53 +0000

This is a record of my journey with Zig, threads, and the tests I made to understand the new std.Io. It's personal - it's not a tutorial. It's my chalkboard.

Why Zig?

I heard about Zig for the first time because of Bun JS. They said it was the fastest runtime in the market. At first, I didn't pay much attention - not my level. But it kept appearing everywhere with the best performance. Why so fast? They said it was written in Zig.

That name caught my curiosity. I had to test Zig.

Now I'm here, fully into Zig. I'm building my own game engine, my own Web framework. But Zig changes a lot, and that's confusing. I use the "master dev" version to access the newest features, but I don't recommend that!

The new std.Io is very different. That's why I started my tests.

The Problem: Threaded vs Evented

In the new Zig std.Io, we have two main ways to handle concurrency:

std.Io.Threaded: Uses a thread pool. Good for CPU-bound tasks (calculations, physics, particles).
std.Io.Evented: Uses io_uring on Linux. Good for I/O-bound tasks (network, files, databases).

But which one should I use? I needed to test it myself.

My Tests

I created several benchmarks to understand the difference. All code is available on my GitHub.

Test 1: CPU-Bound - 1 Million Particles

I simulated 1 million particles with 10 iterations:

// particle_benchmark.zig
fn computeAllParticles(particles: []Particle, dt: f64) void {
    for (particles) |*p| {
        p.x += p.vx * dt;
        p.y += p.vy * dt;
        p.vx *= 0.999;
        p.vy *= 0.999;
    }
}

Results:

Type	Time
Single-threaded	43 ms
Threaded (4 threads)	30 ms (1.4x faster)
Evented	104 ms (slower!)

For CPU-bound work, Threaded is the choice.

Test 2: Network I/O - 100 HTTP Requests

Simulated 100 HTTP requests (5ms delay each):

// network_benchmark.zig
fn simulateNetworkRequest(id: usize) TaskResult {
    var ts: std.posix.timespec = .{ .sec = 0, .nsec = 5_000_000 };
    _ = std.posix.system.nanosleep(&ts, &ts);
    return .{ .id = id, .status = "ok" };
}

Results:

Type	Time
Sequential	503 ms
Concurrent (Evented + Group)	261 ms

For I/O-bound work, Evented with Group is better.

Test 3: Memory Usage

Both use the same memory (~38 MB for 1 million particles). The difference is only thread stack overhead.

What I Learned

CPU-bound tasks → Use Threaded
I/O-bound tasks → Use Evented
The same code works with both - just change the Io implementation

The key is simple:

"Does my task wait for I/O? Use Evented. Does my task do CPU work? Use Threaded."

API Quick Reference

Threaded (for CPU-bound)

var threaded = std.Io.Threaded.init(allocator, .{
    .async_limit = std.Io.Limit.limited(4),
});
const io = threaded.io();
defer threaded.deinit();

var group: std.Io.Group = .init;
group.async(io, myFunction, .{args});
group.await(io) catch {};

Evented (for I/O-bound)

var evented: std.Io.Evented = undefined;
try evented.init(allocator, .{ .thread_limit = 4 });
const io = evented.io();
defer evented.deinit();

var group: std.Io.Group = .init;
group.async(io, myFunction, .{args});
group.await(io) catch {};

Sources

Follow Me

Twitter/X: @1111O11OO11
Email: 7b37b3@gmail.com

Code Repository

All benchmark code available on GitHub.
github.com/llllOllOOll

This article is a personal record of my learning journey with Zig and low-level programming. It's not a tutorial - it's my chalkboard.