Pycon.de: design, generate, deploy: contract-first with fastapi - Evelyne Groen & Kateryna Budzyak¶

Tags: pycon, python

(One of my summaries of the 2025 pycon.de conference in Darmstadt, DE).

They work for a huge marketplace for freelancers. So there’s a matching service, matching project descriptions to freelancers. In between there’s a REST api. Works fine. But… of course there are changes to the api. How do you manage that? One approach is an api contract.

But first the code first approach. A regular fastapy @app.post("/match/{project_id}")-like decorator and a function with some parameters. You can already improve it by using pydantic for more validation of the incoming parameters. Define a “model” in pydantic and pass it to the @app.post().

Fastapi uses the pydantic model when generating the openapi specification. So everything is nicely explicitly specified. See also https://gitlab.com/maltcommunity/public/pycon25 for an example.

A drawback: the implementation of changes is not formalised.

They started using a contract first approach (or: design first approach). You start with an openapi specification and generate the fastapi code. So the other way around. You can find the openapi generator here: https://openapi-generator.tech/ . It works based on mustache templates. You can specifiy your own templates. Of course it only generates the scaffolding, you still have to add your own actual implementation.

This is what they use on the backend in fastapi. Nice: the frontend team also uses the same openapi spec to generate the data models for their client side javascript! This way they are always in sync.

• The openapi spec is the base definition. This created clarity between the teams.

• The spec is in git, the automatically generated files are also in git. And created with CI/CD pipelines.

• The automation works because you can create your own templates to take care of necessary adjustments.

Photo explanation: picture from our 2024 vacation around Kassel (DE)