API Design for MVP Systems

Turning AI capabilities into usable product interfaces

Week 30 • Day 1 • 3 hours

Tonight's Big Idea

A model is only useful when something can call it. APIs are the contract between your ML system and every product, client, and teammate that depends on it. API-first design is how you ship MVPs that don't collapse the first time someone integrates with them.

▶Quick Start — Get Running in 60 Seconds

Grab the starter code and go. Every command below is copy-paste ready.

1. Download & unzip the starter:

curl -LO https://class.wize73.com/W30D1/starter.zip
unzip starter.zip -d week30_product_lab
cd week30_product_lab

2. Install deps and run:

python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r api/requirements.txt
uvicorn api.main:app --reload

3. Confirm it works:

curl http://localhost:8000/health
# {"status":"ok","uptime_seconds":3,"model_loaded":true}
⬇ Download starter.zip 🎮 Open Playground
Stuck before uvicorn starts? Use the Playground's Hosted demo mode — it points at a running copy of the same API on the class server. You can follow along and see every response without installing anything.

1Learning Objectives

By end of session

  • Design a clean API interface for an AI MVP
  • Implement a minimal inference API in FastAPI
  • Document API behavior so other devs can use it

Supporting skills

  • Understand API-first development
  • Define request & response schemas
  • Introduce API versioning strategies
  • Connect endpoints to ML inference workflows

Key Terms

API REST Endpoint Request schema Response schema Inference endpoint Health endpoint API versioning OpenAPI

2The Architecture You're Building Tonight

Every AI product — whether it's a chatbot, a vision system, or a recommendation engine — shares this shape. Your job tonight is the second layer: the stable contract every client and downstream system talks to.

Client
↓

API Layer  ← you are here
↓

Application Logic
↓

ML Model
↓

Response
API-first principle: design the interface before you write the logic. If you can't describe the request and response clearly, the underlying system isn't ready yet.

3Tonight's Schedule

0:00–0:10
Recap & AgendaBridge from W29 user research & DB design into product interfaces.
0:10–0:30
Core: API-First DevelopmentPrinciples, architecture, and why contracts beat code.
0:30–0:55
Breakout 1: Endpoint DesignTeams design endpoints → api/api_design.md
0:55–1:05
Share-outEach team shows one endpoint + the capability it supports.
1:05–1:15
Break
1:15–1:35
Core: Inference APIsFastAPI walkthrough — validation, responses, error handling.
1:35–2:00
Lab Part 1Implement api/main.py with /health and /predict.
2:00–2:25
Breakout 2: API Design ReviewReview another team's design; add validation, missing endpoints, clarity.
2:25–2:35
Break
2:35–2:55
Lab Part 2: DocumentationFinalize api/api_spec.md with versioning + examples.
2:55–3:00
Closing & PreviewW30D2 — ML Pipeline Fundamentals.

4Minimal FastAPI — Tonight's Starting Point

You'll extend this in the lab. Every endpoint you add should have a clear purpose, a typed request, a predictable response, and a documented error condition.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(title="AI Product MVP API", version="1.0.0")

class PredictRequest(BaseModel):
    text: str

class PredictResponse(BaseModel):
    prediction: str
    confidence: float

@app.get("/health")
def health():
    return {"status": "ok"}

@app.post("/predict", response_model=PredictResponse)
def predict(req: PredictRequest):
    # TODO: wire to your ML inference function
    return PredictResponse(prediction="example", confidence=0.85)
Why this shape? Pydantic models turn invalid requests into clean 422 errors before your model code runs. FastAPI auto-generates OpenAPI docs at /docs. Two pieces of infrastructure, for free, the moment you describe your contract.

5Hands-On Lab

Part A — Endpoint Design
Create api/api_design.md. Define POST /predict, GET /health, GET /metadata. For each: purpose, request schema, response schema, error conditions.
Part B — Implementation
Build api/main.py. Run with uvicorn api.main:app --reload.
Part C — Test
Call curl http://localhost:8000/health. Open http://localhost:8000/docs. Try the playground page.
Part D — Documentation
Write api/api_spec.md — endpoint descriptions, example requests/responses, versioning approach.
Anti-GenAI Requirement
Each endpoint must include a "Why this endpoint exists" section that names the product capability it enables. No generic filler.

6Before-Class Reading

REST API Design Best Practices

Resource naming, HTTP methods, request & response design.

restfulapi.net →

FastAPI Official Tutorial

Routes, validation, auto-docs via OpenAPI.

fastapi.tiangolo.com →

API Versioning Strategies

URL, header, and semantic versioning compared.

atlassian.com →

7Weekly Assignment

Submit under week30_product_lab/api/: