> Markdown version of [/videos/1932-for-the-rest-of-us-api-first-and-conway-s-law?t=44](https://www.wearedevelopers.com/videos/1932-for-the-rest-of-us-api-first-and-conway-s-law?t=44). Every page supports `.md` or `Accept: text/markdown`. Links point to the HTML versions so they work for humans too. Agent guide: [/agents.md](https://www.wearedevelopers.com/agents.md).

---

# For the REST of us: API First and Conway’s Law

Michael Jaeger reveals how an API-first approach breaks Conway's Law. Stop building architectures that mirror organizational silos. Discover how collaborative OpenAPI specifications unify cross-team development.

- **Speakers:** [Michael Jaeger](https://www.wearedevelopers.com/@michael-jaeger)
- **Event:** World Congress 2026 Europe - Virtual Stage
- **Published:** July 1, 2026
- **Duration:** 21:29
- **URL:** https://www.wearedevelopers.com/videos/1932-for-the-rest-of-us-api-first-and-conway-s-law

## Summary

Michael Jaeger explores how to overcome Conway's Law—where system structures unavoidably mirror organizational communication boundaries—by adopting an API-first framework. Faced with heterogeneous architectures built by varying internal teams and acquired companies, platforms risk "feeling like different islands" with heavily fragmented APIs. To build a cohesive, unified system, engineering divisions can prioritize designing the API specification collaboratively before writing application code.

Operating the API specification as software itself facilitates smooth cross-team alignment. Housing OpenAPI specifications in a Git repository enables teams to use a standard merge request workflow to refine YAML or JSON syntax collaboratively. This methodology relies on deep modularity; leveraging file references allows developers to establish reusable schemas and minimize payload exposures for enhanced endpoint protection at the architectural level. To prevent organizational bias from creeping back into the shared specifications, standardizing protocols via an internal REST API style guide—drawing on resources like the API Stylebook—ensures consistent handling of HTTP methods, error response codes, and hierarchical URL paths.

While the OpenAPI ecosystem provides massive validation, documentation, and mocking capabilities, organizations must govern codebase generation carefully. Code generators do not guarantee support for particular HTTP frameworks out of the box, necessitating manual configuration when matching specs to specific implementations like a C++ Boost.Beast server. Furthermore, navigating the lack of classical inheritance in standard JSON schema definitions and overcoming limitations around WebSockets (often requiring a companion AsyncAPI approach) emphasizes the need for continuous developer discussion and pragmatic oversight across the broad tooling ecosystem.

**Keywords:** api-first approach, conway's law, rest api guidelines, openapi specification, gitlab merge requests, api endpoint protection, schema modularity, openapi code generators, api stylebook, yaml configuration files, asyncapi integrations, json schema limitations, heterogeneous architectures, c++ boost.beast server, collaborative api design

## Chapters

1. **Experiencing Conway's Law in heterogeneous software systems** (00:44) — How isolated organizational structures create fragmented application landscapes and disconnected integrations.
1. **Adopting API-first development to build cohesive systems** (03:20) — Designing specification limits before writing application code unifies diverse organizational services.
1. **Using Git workflows for collaborative OpenAPI specifications** (04:17) — Tracking text-based API descriptions in version control enables transparent collaboration via merge requests.
1. **Navigating integration caveats in OpenAPI code generators** (06:32) — Aligning open-source generation tools with existing internal C++ HTTP server frameworks prevents integration bugs.
1. **Organizing large OpenAPI descriptions with file references** (08:44) — Splitting specifications across modular files enables the reuse of data schemas and error responses.
1. **Securing external APIs with precise parameter definitions** (10:02) — Narrowing string variables with regular expressions and enumerations prevents malicious code injection.
1. **Minimizing attack vectors through selective API schemas** (11:26) — Referencing specific object attributes builds minimal data models for external customer views.
1. **Resolving REST API structural variations across teams** (13:00) — Standardizing URL paths, entity hierarchies, and HTTP methods eliminates developer style disagreements.
1. **Standardizing design rules using the API Stylebook** (15:54) — Reviewing public REST guidelines helps teams establish and debate domain-specific API rules practically.
1. **Identifying current limitations in the OpenAPI ecosystem** (18:40) — Managing ecosystem shortcomings like missing schema inheritance and inconsistent validation outputs reduces developer friction.

## Related Moments

- [Designing microservices with the OpenAPI specification workflow](https://www.wearedevelopers.com/videos/1046-specifications-as-the-better-way-of-software-development) (from "Specifications as the better way of software development")
- [Automating documentation and code generation with OpenAPI standards](https://www.wearedevelopers.com/videos/759-awful-apis-a-history-lesson-in-industry-mistakes-and-mishaps) (from "Awful APIs: A History Lesson in Industry Mistakes and Mishaps")
- [Bridging design and implementation with modern API specifications](https://www.wearedevelopers.com/videos/1425-lessons-from-our-api-past-evolving-to-a-resilient-api-future) (from "Lessons from Our API Past: Evolving to a Resilient API Future")
- [Implementing API endpoints with restful modeling languages](https://www.wearedevelopers.com/videos/758-why-make-use-of-an-integration-platform-in-today-s-software-developments-and-infrastructure) (from "Why make use of an integration platform in today's software developments and infrastructure?")
- [Understanding the core concepts of API design](https://www.wearedevelopers.com/videos/33-api-design-getting-started) (from "API Design - Getting Started")
- [Summarizing key engineering lessons for platform API development](https://www.wearedevelopers.com/videos/942-insights-from-building-the-canva-developers-platform-to-empower-185-million-designers) (from "Insights from building the Canva Developers Platform to empower 185 million designers")

## Related Articles

- [The CAMARA Project: How Telcos Collaborating Improves Developer Experience](https://www.wearedevelopers.com/magazine/671-the-camara-project-how-telcos-collaborating-improves-developer-experience)
- [The Future of Open Source: A Deep Dive - Scott Chacon at WeAreDevelopers World Congress 2024](https://www.wearedevelopers.com/magazine/471-the-future-of-open-source-a-deep-dive-scott-chacon-at-wearedevelopers-world-congress-2024)
- [Exploring AI: Opportunities and Risks for Developers](https://www.wearedevelopers.com/magazine/522-exploring-ai-opportunities-and-risks-for-developers)
- [Dev Digest 120 - Apple and peers](https://www.wearedevelopers.com/magazine/455-dev-digest-120-apple-and-peers)

## Related Jobs

- [Staff Software Engineer](https://www.wearedevelopers.com/jobs/ext/1425755-staff-software-engineer) at **GitHub**
- [Senior Software Engineer, Client Apps Platform](https://www.wearedevelopers.com/jobs/ext/1773893-senior-software-engineer-client-apps-platform) at **GitHub**
- [Principal Software Engineer, Identity](https://www.wearedevelopers.com/jobs/ext/1469181-principal-software-engineer-identity) at **GitHub**
- [Senior Software Engineer](https://www.wearedevelopers.com/jobs/ext/15942-senior-software-engineer) at **GitHub**
- [Staff Developer Advocate, GitHub Security Lab](https://www.wearedevelopers.com/jobs/ext/1921051-staff-developer-advocate-github-security-lab) at **GitHub**
- [Senior Software Engineer,Billing](https://www.wearedevelopers.com/jobs/ext/1991843-senior-software-engineer-billing) at **GitHub**