Mini-Project - Scoping & Design

calendar_today May 26, 2025 schedule 6 min read

Learning Objectives: By the end of this lesson, you will be able to:

Define the scope and requirements for a small Axum API project

Design endpoints and data models before coding

Identify best practices and common pitfalls in API project planning

1. Welcome and Introduction (5 minutes)

Icebreaker Activity

If you could build any API, what would it do? Share your idea with the group or write it down.

Lesson Overview

Duration: 60 minutes
Prerequisites: Basic Rust knowledge, familiarity with HTTP APIs
Materials Needed: Rust toolchain, code editor, paper/whiteboard for sketching

2. Learning Objectives and Session Outline (5 minutes)

What We’ll Cover Today:

Why scoping and design matter for API projects
How to define requirements, endpoints, and data models
Live demonstration: Scoping a TODO List API
Hands-on practice: Design your own mini-project
Common pitfalls and how to avoid them

Success Criteria:

By the end of this session, you should be able to clearly outline the scope, endpoints, and data models for a small Axum API project.

3. Foundation Knowledge (15 minutes)

Core Concepts

What is Project Scoping?

Project scoping is the process of defining what your project will and will not do. It sets clear boundaries and expectations, helping you avoid feature creep and stay focused.

Real-World Analogy: Think of scoping like planning a road trip: you decide your destination, stops along the way, and what you’ll need. Without a plan, you might get lost or run out of resources.

Why This Matters: Good scoping saves time, reduces bugs, and makes your project easier to maintain and extend.

Designing Endpoints and Data Models

Endpoints are the URLs your API exposes. Data models define the structure of the information your API manages.

Real-World Analogy: Endpoints are like doors to different rooms in a house, and data models are the furniture and layout inside each room.

Why This Matters: Clear endpoints and data models make your API predictable and easy to use.

Key Terminology

Scope: The boundaries of your project—what’s included and what’s not.
Endpoint: A specific URL path that your API responds to (e.g., /todos).
Data Model: The structure of the data your API manages (e.g., a Todo struct).
CRUD: Create, Read, Update, Delete—common operations for managing data.

4. Detailed Explanation and Examples (25 minutes)

Understanding Mini-Project Scoping & Design

Before you write any code, it’s crucial to:

Decide what your API will do (and what it won’t)
List the features you want
Design the endpoints and data models

Practical Applications

Building a TODO List, blog, or URL shortener
Planning features for a team project
Communicating requirements with collaborators

Common Misconceptions

Misconception: “I can add features as I go.” Reality: Unplanned features lead to messy code and delays.
Misconception: “I don’t need to think about errors or validation now.” Reality: Skipping error handling early causes bigger problems later.

5. Live Coding Demonstration (20 minutes)

Example 1: Basic Implementation

// Example: TODO List API
// Endpoints: POST /todos, GET /todos, PUT /todos/{id}, DELETE /todos/{id}
// Data model: struct Todo { id: i32, title: String, completed: bool }
// Features: CRUD, filtering, error handling

Explanation:

The API exposes four main endpoints for managing TODO items.
The Todo struct models each item with an ID, title, and completion status.
Features include basic CRUD operations, optional filtering, and error handling for invalid requests.

Example 2: Practical Application

Suppose you want to build a simple blog API. Here’s how you might scope it:

// Endpoints: POST /posts, GET /posts, GET /posts/{id}, PUT /posts/{id}, DELETE /posts/{id}
// Data model: struct Post { id: i32, title: String, content: String, published: bool }
// Features: CRUD, publish/unpublish, error handling

Key Points:

Start with the core features (CRUD for posts)
Add one or two extra features (e.g., publish/unpublish)
Plan for error handling from the start

Example 3: Advanced Technique

For more complex projects, consider relationships between models:

// Example: Blog with comments
// Endpoints: POST /posts/{id}/comments, GET /posts/{id}/comments
// Data model: struct Comment { id: i32, post_id: i32, author: String, content: String }

Debugging Demonstration

Show common errors and how to fix them:

// Common mistake: Not validating input
// Incorrect
let todo = Todo { id: 1, title: input.title, completed: false };

// Corrected version: Validate title is not empty
if input.title.trim().is_empty() {
    return Err("Title cannot be empty");
}
let todo = Todo { id: 1, title: input.title, completed: false };

6. Hands-On Practice (30 minutes)

Exercise 1: Basic Practice (10 minutes)

Objective: Define the scope for a simple API project.

Instructions:

Choose a project idea (e.g., notes app, recipe manager).
List the main features you want.
Write down the endpoints and data models you’ll need.

Starter Code:

// Fill in your own endpoints and data models
// Endpoints:
// Data models:

Solution:

// Example: Recipe Manager
// Endpoints: POST /recipes, GET /recipes, PUT /recipes/{id}, DELETE /recipes/{id}
// Data model: struct Recipe { id: i32, name: String, ingredients: Vec<String> }

Exercise 2: Intermediate Challenge (10 minutes)

Objective: Add validation and error handling to your design.

Requirements:

Ensure all required fields are present
Plan for invalid input (e.g., empty strings)
Sketch out error responses

Hints:

What should happen if a required field is missing?
How will you communicate errors to the client?

Exercise 3: Creative Application (10 minutes)

Objective: Design a mini-project with at least two related data models (e.g., blog posts and comments).

Challenge:

Define endpoints and data models for both entities
Describe how they relate (e.g., a comment belongs to a post)

Extension Ideas:

Add user authentication
Implement filtering or searching

7. Common Pitfalls and Troubleshooting (5 minutes)

Frequent Mistakes

Problem: Adding features without planning Cause: Excitement or unclear goals Solution: Write down requirements before coding
Problem: Ignoring error handling Cause: Rushing to build features Solution: Plan for errors and validation from the start

Debugging Tips

Use sketches or diagrams to clarify your design
Review your endpoints and data models with a peer
Start small and iterate

8. Best Practices and Professional Tips (5 minutes)

Industry Standards

Keep your API simple and focused
Document endpoints and data models
Validate input and handle errors gracefully

Next Steps in Your Learning Journey

Try building your scoped project in Axum
Explore authentication and authorization
Learn about API documentation tools (e.g., OpenAPI)

9. Summary and Review (5 minutes)

Key Takeaways

Scoping and design are essential for successful API projects
Clear endpoints and data models make your API easier to build and use
Planning for errors and validation saves time later

Quick Review Questions

Why is project scoping important?
What’s the difference between an endpoint and a data model?
How can you avoid common pitfalls in API design?

For Instructors

Teaching Tips

Encourage students to sketch before coding
Use real-world examples to illustrate concepts
Allow time for peer review and discussion

Assessment Ideas

Ask students to submit their project scope and design
Use peer review for feedback
Provide a rubric for evaluating clarity and completeness

Adaptation Notes

For beginners: Focus on one data model and basic CRUD
For advanced students: Add relationships, validation, and error handling
Online: Use collaborative whiteboards or shared docs for design exercises
In-person: Use sticky notes or index cards for endpoints and models