A Guide to Designing RESTful APIs with Clean Code Principles
Designed for Mid-level backend engineers at SaaS companies who are tasked with designing or maintaining REST APIs and want to improve code maintainability and API usability. to spark real collaboration and high-energy learning.
A 90-minute virtual workshop for backend engineers, many of whom inherited legacy APIs plagued by inconsistent naming, unclear error handling, and tech debt. Their stakeholders complain about buggy integrations and steep learning curves for new hires. The session mixes hands-on and live-coding elements, aiming to arm participants with practices they can implement immediately.
API Maze Warmup
Kick off with a visual puzzle: show 3 real-world API endpoint examples, and challenge participants to guess which one is easiest to use—and why. Participants vote using polls or emojis. Then, briefly reveal which was most popular in GitHub projects and why.
Tap to view the full activity.
Why this works
This taps into natural curiosity and frames the session as a practical exploration rather than abstract theory, sparking early engagement.
REST Myths: Fact or Fiction?
Present a series of rapid-fire statements (e.g., 'Every noun should have a plural endpoint', 'PUT always creates new resources'). Participants use colored cards or type 'Fact' or 'Fiction' in chat. Each answer is debunked or affirmed with a 20-second explanation.
Tap to view the full activity.
Why this works
Surfacing misconceptions early prevents reinforcement of faulty mental models and opens participants to new learning.
Endpoint Makeover: Silent Sketch
Share a cluttered, confusing API endpoint description via screen share or handout. Ask everyone to spend 2 minutes sketching or jotting down a cleaner version—no code required, just structure or naming improvements. Volunteers can share their sketches in chat or hold them to the camera.
Tap to view the full activity.
Why this works
Promotes low-pressure, creative thinking and ensures everyone mentally rehearses the skill before discussion.
Battle of the Endpoints
Split attendees into small teams and give each a messy real-world API snippet. Each team has 5 minutes to rewrite it using Clean Code principles, then pitch their ‘before and after’ in a 30-second micro-presentation. Fast-paced, with a playful competitive spirit.
Tap to view the full activity.
Why this works
Energizes the room, fosters teamwork, and cements learning by applying principles under time pressure.
Integration Horror Stories
Share a true, anonymized story of a developer who wasted days integrating with a poorly designed API (e.g., unclear error codes, inconsistent endpoints, surprise breaking changes). Pause and ask, 'What could have prevented this?' Invite reactions in chat or aloud, steering toward specific Clean Code interventions.
Tap to view the full activity.
Why this works
Real stories create emotional stakes, making abstract best practices feel urgent and tangible.
Clean Code Commitment Postcard
Each participant writes a digital or physical postcard to their ‘future self’ describing one Clean Code API principle they promise to use next week. Optionally, participants share theirs in chat or on a shared board. Facilitator collects and schedules a reminder email for accountability.
Tap to view the full activity.
Why this works
Reflection and personal commitment increase transfer of learning and signal intention to act, supported by a public or private pledge.
Sign up to unlock 3 more activities
Get the full pack, facilitation flow, and more ready-to-run ideas.