Building Better APIs — Resources

Slides, recording, demo code, and references for the OpenAPI talk at Grazer Linuxtage 2025.

Resources for Building Better APIs: From Django to Client Libraries with OpenAPI, presented at Grazer Linuxtage 2025.

Take It Home

Slides - the full deck.
Recording (media.ccc.de) - also on YouTube.
glt25-demo - the Django REST Framework API used in the talk, with versioned openapi.yaml schema releases.
glt25-client - the client library generated from that schema.

Following Along With the Code

The two repositories are built to be read step by step.

glt25-demo — the Django API as a guided progression. Each step of the talk is its own branch, from step-1 (initial setup) through step-17. Check out a branch to jump to that point, for example git checkout step-12 to land where drf-spectacular is added. main is the starting point.

Three branches are tagged as published schema versions, and each tag ships an openapi.yaml release:

v1 (step-15) - the first stable schema: list view plus nested create.
v2 (step-16) - a backward-compatible change, adding rating to the car model. Clients built for v1 keep working.
v3 (step-17) - a breaking change, renaming name to brand on the manufacturer. Clients built for v1/v2 need regenerating.

glt25-client — the generated client libraries (Python and Angular). The v1, v2, and v3 branches are each generated from the matching demo schema, so they line up one-to-one:

demo tag v1 → openapi.yaml v1 release → client branch v1
demo tag v2 → openapi.yaml v2 release → client branch v2
demo tag v3 → openapi.yaml v3 release → client branch v3

Pick the client branch for the API version you target. main holds the generator scripts (build-python.sh, generate-angular.sh) if you want to regenerate a client from any schema yourself.

Building better APIs: from Django to client libraries with OpenAPI - guest post on the Django Software Foundation weblog.
Building sustainable APIs: Anexian Harald tells you how - Anexia article about the talk (German version).

Tools and References

drf-spectacular - OpenAPI 3 schema generation for Django REST Framework.
OpenAPI Generator - generate client libraries from an OpenAPI schema.
openapi-diff - compare two OpenAPI schemas to spot breaking changes.
Django REST Framework - the API framework used throughout the talk.