Designing Python APIs with FastAPI — and Why I Built Sonobe

Python is the language I reach for when the problem is really about logic: APIs, automation, data-shaped work, and the frameworks themselves. It is one of my professional core technologies, I teach programming with it, and it is the foundation of Sonobe, the backend framework I built. Python’s advantage at this point is not fashion; it is the combination of a huge, mature ecosystem and code that stays readable when the original author — often me — comes back to it a year later.

Within Python, though, “which framework?” is a real architectural decision, and I use two answers professionally: FastAPI and Django. They are not interchangeable, and pretending otherwise is how teams end up rebuilding an admin panel inside a micro-framework or fighting an ORM inside a latency-sensitive service.

FastAPI’s core bet is that types are documentation that cannot drift. You declare request and response models once, and validation, serialization, and OpenAPI documentation all follow from the same source of truth. In my Laravel article I argued an API is a contract; FastAPI is the framework that most literally encodes that contract in the type system. For API-first services — especially ones consumed by other services, frontends you do not control, or increasingly, by agents — that explicitness is worth a great deal.

The async story matters too, but honestly, in the order of real-world importance it comes second. Most APIs are I/O-shaped, and FastAPI handles that well, yet the projects I have seen succeed with it did so because the contracts were clear and the codebase stayed navigable, not because a benchmark number was bigger. Speed gets a framework adopted; clarity is what keeps it alive in year three.

Django is the opposite trade, and often the right one. When the product needs an admin, authentication, migrations, and a decade of solved problems on day one, Django’s batteries are not bloat — they are weeks of work you do not have to do or maintain. I use Django professionally alongside FastAPI and Laravel, choosing per project rather than per loyalty.

My working rule is simple. If the API is the product — consumed by machines, versioned, contract-driven — FastAPI leads. If the application is the product — users, admin, content, business workflows — Django usually leads, possibly with its REST layer where needed. The expensive mistake is not picking the “wrong” one once; it is spending months rebuilding the other framework’s strengths inside your choice.

After enough FastAPI projects, the same friction kept appearing. Features wanted to be added without reaching into the core of the application. Modules wanted clearer boundaries than “one growing folder of routers”. So I built Sonobe on top of FastAPI: a modular, decoupled core where custom features are packaged as plug-and-play extensions instead of edits to shared code. It is the same instinct I later took to the frontend with Yoshi — boundaries first, convenience second, because boundaries are what still exist after the convenience wears off.

Building a framework on a framework sounds indulgent until you price the alternative. Every serious codebase grows an internal framework anyway — conventions, helpers, module patterns — it just usually grows it accidentally, undocumented, in the spaces between features. Sonobe is that layer made deliberate: named, structured, and reusable across projects instead of reinvented inside each one. The framework is built; its source is not public yet, and I plan to open-source it.

One design decision in Sonobe matters more every year: it generates documentation for people and for development agents — human-readable docs, agent skills, and MCP support. This sounds like a feature list until you watch how software is actually built now. Agents read your codebase. If the only accurate description of your system lives in a senior developer’s head, both the new hire and the agent are guessing.

FastAPI’s typed contracts turn out to be an excellent base for this, because machine-readable truth already exists in the models. My developer tooling work keeps circling the same idea from different sides: the systems that age well are the ones whose structure can be explained — to a teammate, to a future maintainer, or to an agent about to modify them. PromptForge approaches it from the brief; Sonobe from the framework itself.

If you are choosing today, I would decide in this order. First, is the product an API or an application? Second, who consumes it — your own frontend, third parties, agents? Third, how much of Django’s battery pack would you otherwise rebuild by hand? Answer those honestly and the framework mostly chooses itself. What I would not do is choose by benchmark screenshots; none of my production pain has ever come from the framework’s requests-per-second ceiling.

For my own work the map is stable now: FastAPI for contract-first services and as Sonobe’s foundation, Django when the application needs its batteries, Laravel when the project is PHP-shaped, and Rust when the system needs that grade of control. Frameworks are tools; the craft is knowing which problem you actually have. The adoption path I recommend to teams is gradual: start with one contained service — a document converter, a reporting endpoint, a small integration — put it behind the same authentication as the main system, and let the team get comfortable with its deploy, logging, and rollback story before giving it more responsibility. A framework choice is a maintenance choice: what matters is not only how fast the first version ships, but how calmly the tenth change lands — and FastAPI has consistently given me calm tenth changes. If yours is a Python API that needs building properly, start from my résumé and let’s talk.