There are Web APIs everywhere, from the classic REST/HTTP, to GraphQL, to gRPC, we rely on them to get things done each and every day. But how much do we think about the design of these APIs? How do you document an API once you've created it? What even is versioning? Do we really understand HTTP? In this episode, Kris and the panel are joined by Jamie Tanna to discuss APIs, their design, how to document them, and more.

Thank you for being a supporter!

Thanks for tuning in and happy listening!

Notes:

• Addition REST papers (12:04)
  • Computational REST (dissertation)
  • From representations to computations: the evolution of web architectures
  • CREST: A new model for Decentralized, Internet-Scale Applications
  • COmputAtional State Transfer: An Architectural Style for Secure Decentralized Systems
  • Reflections on the REST architectural style and "principled design of the modern web architecture" (impact paper award)
  • From representations to computations: the evolution of web architectures
• Web API Versioning Is Insufficient (36:26)
• http.cat (01:17:51)
• Awesome Identifiers (01:28:51)
• Please Stop Saying "just" (01:44:03)
• jvt.me/elsewhere (01:45:19)

Table of Contents:

• Intro (00:00)
• Prologue (01:15)
  • Introducing Jamie Tanna (01:15)
• Preface - APIs: The Leaky Kitchen Sink of Software (02:14)
  • What is an API? (03:13)
  • Interfaces & Design (08:04)
  • What is REST? (11:52)
  • Leaky Data Models (14:57)
  • URLS are a leaky kitchen sink (18:28)
  • URLs are concepts (21:31)
  • Negotiating Content Negotiation (24:02)
  • Embrace Flexibility (27:49)
• Chapter 1 - Versioning & Breaking Changes (30:03)
  • What is a breaking change? (30:05)
  • Communicating breaking changes (33:05)
• Chapter 2 - API: Annoying Perpetual Interface (36:20)
  • APIs as Contracts (36:20)
  • APIs require planning (44:40)
• Chapter 3 - Documenting Designs (49:22)
  • Can OpenAPI save us? (49:22)
  • Design through documentation (58:28)
  • Innovation & API/Transport Separation (01:02:09)
• Interlude - Version 0 Forever! (01:11:48)
• Chapter 4 - An Exploration of HTTP (01:12:14)
  • HTTP and it's Status Codes (01:12:14)
• Chapter 5 - Identifying Identifiers (01:25:30)
  • How to choose identifiers (01:25:30)
• Appendix UNPOP - Unpopular Opinions (01:30:03)
  • Dylan's Unpop (01:30:48)
  • Jamie's Unpop (01:33:52)
  • Matt's Unpop (01:39:37)
  • Ian's Unpop (01:41:19)
  • Kris' Unpop (01:42:49)
  • Just stop using just (01:44:03)
• Epilogue (01:45:15)
  • Where to find Jamie (01:45:15)
• Outro (01:45:29)

Hosts

• Website
• Bluesky
• Threads
• X/Twitter
• LinkedIn
• Instagram

• (00:00) - Intro