# AT-Jet Quick Start
Get a Protobuf API server running in 5 minutes.
## Prerequisites
- Rust 1.75+ (required by axum 0.7)
- `protoc` (Protocol Buffers compiler)
```bash
# macOS
brew install protobuf
# Ubuntu/Debian
apt install protobuf-compiler
# Verify installation
protoc --version
```
## Step 1: Create Project
```bash
cargo new my-api
cd my-api
```
## Step 2: Add Dependencies
Edit `Cargo.toml`:
```toml
[package]
name = "my-api"
version = "0.1.0"
edition = "2021"
[dependencies]
at-jet = "0.6"
tokio = { version = "1", features = ["full"] }
prost = "0.13"
anyhow = "1"
[build-dependencies]
prost-build = "0.13"
```
## Step 3: Define Protobuf Schema
Create `proto/user.proto`:
```protobuf
syntax = "proto3";
package myapi;
message User {
int32 id = 1;
string name = 2;
string email = 3;
}
message CreateUserRequest {
string name = 1;
string email = 2;
}
message ListUsersResponse {
repeated User users = 1;
int32 total = 2;
}
```
## Step 4: Add Build Script
Create `build.rs`:
```rust
fn main() {
prost_build::compile_protos(&["proto/user.proto"], &["proto/"]).unwrap();
}
```
## Step 5: Write Server
Edit `src/main.rs`:
```rust
use at_jet::prelude::*;
// Include generated protobuf code
pub mod proto {
include!(concat!(env!("OUT_DIR"), "/myapi.rs"));
}
use proto::{CreateUserRequest, ListUsersResponse, User};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
// Initialize tracing (unified setup with sensible defaults)
let _guard = init_tracing(&TracingConfig::default());
let server = JetServer::new()
.route("/health", get(health))
.route("/api/users", get(list_users).post(create_user))
.route("/api/users/:id", get(get_user))
.with_cors()
.with_compression()
.with_tracing();
tracing::info!("Server running on http://0.0.0.0:8080");
server.serve_with_shutdown("0.0.0.0:8080").await?;
Ok(())
}
async fn health() -> &'static str {
"OK"
}
async fn list_users() -> ProtobufResponse<ListUsersResponse> {
let response = ListUsersResponse {
users: vec![
User { id: 1, name: "Alice".into(), email: "alice@example.com".into() },
User { id: 2, name: "Bob".into(), email: "bob@example.com".into() },
],
total: 2,
};
ProtobufResponse::ok(response)
}
async fn get_user(Path(id): Path<i32>) -> ProtobufResponse<User> {
let user = User {
id,
name: "Alice".into(),
email: "alice@example.com".into(),
};
ProtobufResponse::ok(user)
}
async fn create_user(
ProtobufRequest(req): ProtobufRequest<CreateUserRequest>,
) -> ProtobufResponse<User> {
let user = User {
id: 100,
name: req.name,
email: req.email,
};
ProtobufResponse::created(user)
}
```
## Step 6: Run
```bash
cargo run
```
## Step 7: Test
### Using JetClient (Rust)
Create `examples/client.rs`:
```rust
use at_jet::prelude::*;
pub mod proto {
include!(concat!(env!("OUT_DIR"), "/myapi.rs"));
}
use proto::{CreateUserRequest, ListUsersResponse, User};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let client = JetClient::new("http://localhost:8080")?;
// GET request
let users: ListUsersResponse = client.get("/api/users").await?;
println!("Total users: {}", users.total);
// GET with path parameter
let user: User = client.get("/api/users/1").await?;
println!("User: {} ({})", user.name, user.email);
// POST request
let req = CreateUserRequest {
name: "Charlie".into(),
email: "charlie@example.com".into(),
};
let created: User = client.post("/api/users", &req).await?;
println!("Created user ID: {}", created.id);
Ok(())
}
```
Run with:
```bash
cargo run --example client
```
### Using curl
```bash
# Health check
curl http://localhost:8080/health
# List users (Protobuf response - binary)
curl -H "Accept: application/x-protobuf" http://localhost:8080/api/users
# With JSON (requires debug key - see User Guide)
```
## Next Steps
- [User Guide](USER_GUIDE.md) - Complete feature documentation
- [Architecture](ARCHITECTURE.md) - Design decisions and rationale
- [Examples](../examples/) - More code examples
### Optional Features
Once your basic server is running, consider enabling:
```toml
# Prometheus metrics
at-jet = { version = "0.6", features = ["metrics"] }
# Jaeger distributed tracing
at-jet = { version = "0.6", features = ["tracing-otel"] }
# JWT authentication middleware
at-jet = { version = "0.6", features = ["jwt"] }
# In-memory session management
at-jet = { version = "0.6", features = ["session"] }
```
See [User Guide](USER_GUIDE.md) for details on each feature.
## Common Issues
### `protoc not found`
Install Protocol Buffers compiler:
```bash
# macOS
brew install protobuf
# Ubuntu
sudo apt install protobuf-compiler
```
### Build fails with prost errors
Ensure your `proto/` directory exists and contains valid `.proto` files.
### Connection refused
Make sure the server is running before testing with the client.