Creating Your First Project
This guide walks you through creating a complete REST API from scratch. By the end, you'll have a running FastAPI application with database models, migrations, and CRUD endpoints.
Step 1: Create the Project​
The fastman new command generates a full project structure with all the boilerplate already configured:
fastman new blog-api
You can also specify options upfront to skip interactive prompts:
fastman new blog-api --pattern=feature --database=postgresql --package=uv
Available Options​
| Option | Values | Default |
|---|---|---|
--pattern | feature, api, layer | feature |
--database | sqlite, postgresql, mysql, oracle, firebase | sqlite |
--package | uv, poetry, pipenv, pip | auto-detected |
If you're not sure, go with the default feature pattern. It organizes code into vertical slices (each feature is self-contained) and scales well from small APIs to large applications. See Architecture Patterns for a detailed comparison.
Step 2: Understand the Project Structure​
After creation, your project looks like this:
blog-api/
├── app/
│ ├── core/ # Shared infrastructure
│ │ ├── config.py # Pydantic settings loaded from .env
│ │ ├── database.py # SQLAlchemy engine and session setup
│ │ └── dependencies.py # FastAPI dependency injection
│ ├── features/ # Feature modules (vertical slices)
│ └── main.py # Application entry point & router mounting
├── database/
│ ├── migrations/ # Alembic migration files
│ └── seeders/ # Database seeder classes
├── tests/ # Test files
├── .env # Environment variables (DATABASE_URL, SECRET_KEY, etc.)
└── pyproject.toml # Python dependencies
Step 3: Start the Development Server​
cd blog-api
fastman serve
Your API is now running at http://localhost:8000.
Visit http://localhost:8000/docs for the interactive Swagger documentation — this is auto-generated by FastAPI from your endpoint definitions.
Step 4: Create Your First Feature​
Let's add a posts feature with full CRUD endpoints:
fastman make:feature post --crud
This creates a complete feature module:
app/features/post/
├── __init__.py
├── models.py # SQLAlchemy model (Post table)
├── schemas.py # Pydantic schemas (create, update, response)
├── service.py # Business logic layer
└── router.py # API endpoints (GET, POST, PUT, DELETE)
Step 5: Run Migrations​
Your new model needs a database table. Create and apply a migration:
# Generate a migration from your model changes
fastman make:migration "create posts table"
# Apply the migration to the database
fastman database:migrate
Step 6: Test Your API​
Restart the server (fastman serve) and open http://localhost:8000/docs. You'll see your new endpoints:
| Method | Endpoint | Description |
|---|---|---|
GET | /posts | List all posts |
POST | /posts | Create a new post |
GET | /posts/{id} | Get a specific post |
PUT | /posts/{id} | Update a post |
DELETE | /posts/{id} | Delete a post |
Try creating a post using the Swagger UI's "Try it out" button!
Next Steps​
- Add JWT authentication — secure your endpoints
- Understand the architecture patterns — learn why features are organized this way
- Explore all scaffolding commands — generate models, services, middleware, and more
- Seed your database — populate test data