A simple HTTP API server written in Zig.
- REST-style API endpoints
- JSON request/response handling
- Sample Users and Posts resources
- HTTP method support (GET, POST)
- Basic error handling with proper HTTP status codes
- Health check endpoint
- Configuration via environment variables
- Zig 0.14.0 or newer
# Show all available commands
make help
# Build (debug)
make build
# Build (release - optimized)
make release
# Run server
make run
# Run with custom port
make run PORT=8099# Build for all platforms
make build-all
# Build for specific platforms
make build-linux # Linux x86_64
make build-linux-arm64 # Linux ARM64
make build-windows # Windows x86_64
make build-macos # macOS (native)
make build-macos-x64 # macOS Intel# Build
zig build
# Build release
zig build -Doptimize=ReleaseFast
# Run
zig build run./zig-out/bin/zig-http-serverBy default the server listens on http://127.0.0.1:9099.
HOST: bind address (default:127.0.0.1)PORT: bind port (default:9099)
Example:
HOST=0.0.0.0 PORT=9099 zig build run# Build multi-arch image (amd64 + arm64)
make docker
# Build for specific architecture
make docker-amd64
make docker-arm64
# Run container
make docker-run
# Build with custom version
make docker VERSION=1.0.0docker buildx build \
--platform linux/amd64,linux/arm64 \
--build-arg VERSION=0.1.0 \
--build-arg VCS_REF="$(git rev-parse --short HEAD 2>/dev/null || echo unknown)" \
--build-arg BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-t zig-http-server:0.1.0 .Run (defaults inside container: HOST=0.0.0.0, PORT=9099):
docker run --rm -p 9099:9099 zig-http-server:0.1.0Interactive API documentation is available via Swagger UI:
- Swagger UI: http: 8000 //localhost:9099/docs
- OpenAPI Spec: http://localhost:9099/openapi.json
GET /Returns a short help text with available endpoints.
GET /docsSwagger UI - Interactive API documentation.
GET /openapi.jsonOpenAPI 3.0 specification in JSON format.
GET /api/healthChecks server health.
Response:
{
"status": "ok",
"timestamp": 1234567890
}GET /api/usersResponse:
[
{
"id": 1,
"name": "John Doe",
"email": "john@example.com"
},
{
"id": 2,
"name": "Jane Smith",
"email": "jane@example.com"
}
]GET /api/users/:idResponse:
{
"id": 1,
"name": "John Doe",
"email": "john@example.com"
}POST /api/users
Content-Type: application/json
{
"name": "New User",
"email": "new@example.com"
}Response:
{
"id": 999,
"name": "New User",
"email": "new@example.com"
}GET /api/postsResponse:
[
{
"id": 1,
"title": "Getting Started with Zig",
"content": "Zig is a modern systems programming language.",
"author_id": 1
}
]POST /api/posts
Content-Type: application/json
{
"title": "New Post Title",
"content": "Post content goes here.",
"author_id": 1
}Response:
{
"id": 999,
"title": "New Post Title",
"content": "Post content goes here.",
"author_id": 1
}# Health check
curl http://127.0.0.1:9099/api/health
# List users
curl http://127.0.0.1:9099/api/users
# Get user
curl http://127.0.0.1:9099/api/users/1
# Create user
curl -X POST http://127.0.0.1:9099/api/users \
-H "Content-Type: application/json" \
-d '{"name":"Test User","email":"test@example.com"}'
# List posts
curl http://127.0.0.1:9099/api/posts
# Create post
curl -X POST http://127.0.0.1:9099/api/posts \
-H "Content-Type: application/json" \
-d '{"title":"Test Post","content":"Test content","author_id":1}'zig-http-server/
├── build.zig # Build configuration
├── src/
│ └── main.zig # Server implementation
└── README.md # This file
zig build testThis project uses GitHub Actions for CI/CD:
| Workflow | Trigger | Description |
|---|---|---|
| CI | Push/PR to main |
Build, test, cross-compile |
| Docker | Tags v*, push to main |
Build & push multi-arch Docker image |
-
Create and push a tag:
git tag v1.0.0 git push origin v1.0.0
-
GitHub Actions will:
- Build binaries for Linux (amd64, arm64) and Windows
- Create a GitHub Release with all binaries
- Build and push Docker image to
ghcr.io/bariiss/zig-http-server
# Pull from GitHub Container Registry
docker pull ghcr.io/bariiss/zig-http-server:latest
# Run
docker run --rm -p 9099:9099 ghcr.io/bariiss/zig-http-server:latest- This server is intended for learning/demo purposes.
- Data is currently in-memory sample data; a real backend would persist to a database.
- Routing is intentionally simple; consider a router library for more complex needs.
Educational/demo use.