ralph-claude-code/examples/rest-api

Example: REST API with Specifications

This example shows a medium-complexity Ralph configuration for a bookstore REST API. It demonstrates when and how to use the specs/ directory.

What This Example Demonstrates

• Focused PROMPT.md - High-level goals and principles
• Detailed specs/api.md - Endpoint specifications that are too detailed for PROMPT.md
• Structured fix_plan.md - Tasks organized by feature area

Project Structure

rest-api/
├── .ralph/
│   ├── PROMPT.md         # Project vision and principles
│   ├── fix_plan.md       # Implementation tasks
│   └── specs/
│       └── api.md        # Detailed API specifications
├── .ralphrc              # Configuration (auto-generated)
└── README.md             # This file

Why This Example Uses specs/

The PROMPT.md keeps things high-level:

• What the API is for (bookstore inventory)
• Technology stack (FastAPI, PostgreSQL)
• Key principles (REST conventions, authentication)

But the API needs detailed specifications that would clutter PROMPT.md:

• Exact request/response formats
• Validation rules
• Error codes
• Pagination behavior

That's what specs/api.md is for.

How to Use This Example

1. Copy this directory to a new location:

   cp -r examples/rest-api ~/my-bookstore-api
   cd ~/my-bookstore-api
   

2. Initialize git and Python environment:

   git init
   python -m venv venv
   source venv/bin/activate
   pip install fastapi uvicorn sqlalchemy pytest
   

3. Run Ralph:

   ralph --monitor
   

Key Points

PROMPT.md Sets Direction

PROMPT.md answers "what are we building and how?" without getting into implementation details.

specs/api.md Provides Details

When you need to specify:

• Exact endpoint paths and methods
• Request/response schemas
• Business rules and constraints
• Error handling behavior

These details help Ralph implement correctly on the first try.

fix_plan.md References specs/

Notice how tasks reference the specification:

- [ ] Implement book endpoints per specs/api.md

This tells Ralph where to find the detailed requirements.

When to Add More Specs

Consider adding additional spec files for:

• specs/database.md - Schema details, relationships, indexes
• specs/auth.md - Token formats, permission rules, session handling
• specs/stdlib/errors.md - Standard error response format
• specs/stdlib/pagination.md - Pagination conventions

Comparison with Simple Example

Aspect	Simple CLI	REST API
Complexity	Low	Medium
Uses specs/	No	Yes
PROMPT.md length	~40 lines	~30 lines
Why	Self-contained	API contracts need detail