Examples¶

Real-world patterns demonstrating mockapi-server capabilities.

Complete Working Examples¶

For ready-to-run example projects, see the examples/ directory:

Basic - Simple User and Product API with interactive HTML client
Blog - Multi-model relationships (User, Post, Comment) with Docker setup
E-commerce - Complex e-commerce system with Postman collection

Each example includes complete Pydantic models, setup instructions, and testing tools.

Code Patterns¶

Below are code snippets demonstrating common usage patterns:

Basic User API¶

Simple single-model API.

# models.py
from datetime import datetime
from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    email: str
    created_at: datetime

mockapi-server serve --models models.py --generate-data --data-count 20

Test endpoints:

curl http://localhost:3000/api/v1/users
curl http://localhost:3000/api/v1/users/1

curl -X POST http://localhost:3000/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"id": 999, "name": "Test", "email": "test@example.com", "created_at": "2025-01-10T10:00:00Z"}'

Blog with Relationships¶

Multi-model API with foreign keys.

# models.py
from datetime import datetime
from pydantic import BaseModel

class User(BaseModel):
    id: int
    username: str
    email: str
    created_at: datetime

class Post(BaseModel):
    id: int
    title: str
    content: str
    author_id: int  # FK to User
    published_at: datetime | None = None

class Comment(BaseModel):
    id: int
    text: str
    post_id: int  # FK to Post
    user_id: int  # FK to User
    created_at: datetime

mockapi-server serve --models models.py --generate-data --data-count 50

Query relationships:

# Get user's posts
curl "http://localhost:3000/api/v1/posts?author_id=1"

# Get post's comments
curl "http://localhost:3000/api/v1/comments?post_id=5"

Foreign keys automatically reference valid IDs.

Pagination¶

Page-based:

curl "http://localhost:3000/api/v1/users?page=1&page_size=10"

Offset-based:

curl "http://localhost:3000/api/v1/users?offset=0&limit=10"

Both return items array with pagination metadata including has_next and has_prev.

Frontend Integration¶

Using mock API with React/Vue/etc.

// api.js
const API_BASE = "http://localhost:3000/api/v1";

export const api = {
  async getUsers() {
    const response = await fetch(`${API_BASE}/users`);
    return response.json();
  },

  async getUser(id) {
    const response = await fetch(`${API_BASE}/users/${id}`);
    return response.json();
  },

  async createUser(data) {
    const response = await fetch(`${API_BASE}/users`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    });
    return response.json();
  },

  async updateUser(id, data) {
    const response = await fetch(`${API_BASE}/users/${id}`, {
      method: "PUT",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    });
    return response.json();
  },

  async deleteUser(id) {
    await fetch(`${API_BASE}/users/${id}`, { method: "DELETE" });
  },
};

React example:

// UserList.jsx
import { useEffect, useState } from "react";
import { api } from "./api";

function UserList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    api.getUsers().then((data) => {
      setUsers(data);
      setLoading(false);
    });
  }, []);

  if (loading) return <div>Loading...</div>;

  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>
          {user.name} - {user.email}
        </li>
      ))}
    </ul>
  );
}

Configuration¶

Use mockapi-server.yml for project settings:

# mockapi-server.yml
seed_count: 100
port: 3000
log_level: INFO
cors_enabled: true
cors_origins:
  - "http://localhost:3001"
  - "http://localhost:8080"

mockapi-server serve --models models.py --config mockapi-server.yml --generate-data