# OpenAPI & API design

Page: https://stenobird.com/podcast/go-time-golang-software-engineering/openapi-api-design
Text version: https://stenobird.com/podcast/go-time-golang-software-engineering/openapi-api-design.md
Podcast: [Go Time: Golang, Software Engineering](https://stenobird.com/podcast/go-time-golang-software-engineering)
Published: 2024-08-08T14:15:00+00:00
Episode link: https://changelog.com/gotime/328
Audio file: https://op3.dev/e/https://cdn.changelog.com/uploads/gotime/328/go-time-328.mp3
Processing state: processed
JSON: https://stenobird.com/v1/public/podcasts/go-time-golang-software-engineering/episodes/openapi-api-design
Duration seconds: 4452

## Resource

A deep dive into the complexities of API design, focusing on the utility of OpenAPI for structured documentation and type generation. The discussion explores the tension between versioning strategies and the difficulty of maintaining backward compatibility in evolving ecosystems.

## Highlights
- Main idea: OpenAPI serves as a structured alternative to unstructured, unmaintained text-based documentation
- Practical takeaway: Using tools like oapi-codegen allows for the automated generation of models, types, and clients to ensure consistency
- Failure mode: Treating major version bumps as a way to avoid the hard work of managing granular, backward-compatible changes
- Main idea: Effective API design requires thinking about automated upgrade paths and migration recipes rather than just breaking changes
- Practical takeaway: Open source sustainability relies on active contributor coaching and new funding models like GitHub Sponsors

## Topics

OpenAPI, API Design, Software Engineering, Code Generation, Versioning, Open Source Maintenance, Go Programming, Cloud Development Environments

## Chapters
- 1:00 — Cloud Development Environments: An introduction to Coder and how cloud-based infrastructure can standardize development environments for large engineering teams.
- 6:30 — The Value of OpenAPI: Moving beyond unstructured documentation to JSON/YAML-based specifications that define API behavior precisely.
- 12:10 — Customizing Code Generation: Discussing the ability to override templates in code generation tools to meet specific internal architectural needs.
- 17:35 — Generating Clients and Models: The primary benefits of using OpenAPI for generating usable SDKs, request/response models, and type-safe clients.
- 23:05 — The Versioning Dilemma: The difficulty of managing API changes and versioning when acting as a service provider for other internal teams.
- 28:50 — The Cost of Breaking Changes: Analyzing the friction caused by major version jumps and the importance of creating seamless migration paths.
- 34:45 — Infrastructure and Compatibility: Understanding the responsibility of consumers to abide by the evolving specifications of the infrastructure they build upon.
- 40:20 — Automation in API Evolution: Exploring the potential for automated transformations to help developers migrate between API versions without manual effort.

## Actions

- request_transcript: `POST https://stenobird.com/v1/public/podcasts/go-time-golang-software-engineering/episodes/openapi-api-design/transcription-requests` — Idempotently request low-priority transcript generation for this episode.
- read_markdown: `GET https://stenobird.com/podcast/go-time-golang-software-engineering/openapi-api-design.md` — Read the agent-friendly Markdown representation of this episode resource.

A page view does not enqueue transcription. Agents should invoke `request_transcript` explicitly when they need this episode processed.

## Transcript

Full transcripts are not published on public pages unless there is a clear rights basis.