<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/">
  <channel>
    <title>Team Collaboration · Jared Lynskey</title>
    <link>https://jared.lynskey.co.nz/en/tags/team-collaboration/</link>
    <description>Short stories of value on software engineering and engineering leadership — performance reviews, hiring and scaling teams, CI/CD, DevOps monitoring and agentic AI. Written from Seoul.</description>
    <generator>Hugo</generator>
    <language>en</language>
    <copyright>© 2026 Jared Lynskey</copyright>
    <lastBuildDate>Mon, 26 Oct 2026 00:00:00 +1300</lastBuildDate>
    <atom:link href="https://jared.lynskey.co.nz/en/tags/team-collaboration/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>API-First Development with OpenAPI: Frontend and Backend in Parallel</title>
      <link>https://jared.lynskey.co.nz/en/posts/2023/2023-10-08-open-api/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/en/posts/2023/2023-10-08-open-api/</guid>
      <pubDate>Sun, 08 Oct 2023 00:30:03 +0000</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>OpenAPI</category>
      <category>Backend</category>
      <category>Frontend</category>
      <category>API Design</category>
      <category>Software Development</category>
      <category>Team Collaboration</category>
      <description>API-first development in practice: agree on the OpenAPI contract first, stand up a mock server, and the frontend stops waiting on the backend.</description>
      <content:encoded><![CDATA[<p>The most reliable schedule-killer I&rsquo;ve seen isn&rsquo;t hard engineering — it&rsquo;s the frontend sitting around waiting for an endpoint that&rsquo;s &ldquo;almost done&rdquo;. The fix we&rsquo;ve settled on at work is boring and effective: agree on the API contract first, in OpenAPI, before anyone writes code.</p>

<h3 class="relative group">The waiting game
    <div id="the-waiting-game" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#the-waiting-game" aria-label="Anchor">#</a>
    </span>
    
</h3>
<p>The traditional flow is sequential. Backend designs and builds the API, and only once the endpoints actually work does frontend start integrating. Every backend delay lands directly on the frontend&rsquo;s calendar, and the frontend&rsquo;s calendar is usually where the release date lives.</p>

<h3 class="relative group">Contract first, code second
    <div id="contract-first-code-second" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#contract-first-code-second" aria-label="Anchor">#</a>
    </span>
    
</h3>
<p>With a schema-first flow, both sides start almost at the same time. Before any code exists, the API&rsquo;s structure goes into an OpenAPI schema — every endpoint, request and response model, auth method and error code. That document becomes the contract between frontend and backend.</p>
<p>The payoff is immediate. Everyone understands the feature the same way before it&rsquo;s built. Frontend can build UI while backend is still implementing. Changes move faster because there&rsquo;s one agreed source of truth to update. And you can generate a mock server straight from the schema, so frontend testing starts before a single real endpoint exists.</p>

<h3 class="relative group">How it runs in practice
    <div id="how-it-runs-in-practice" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#how-it-runs-in-practice" aria-label="Anchor">#</a>
    </span>
    
</h3>
<ol>
<li>Gather requirements, same as for anything.</li>
<li>Design the schema: endpoints, request/response models, authentication, error codes.</li>
<li>Have both frontend and backend review it — this is where the contract earns its keep.</li>
<li>Generate a mock server (Swagger and Postman both do this) and let frontend integrate against it.</li>
<li>Backend implements the real endpoints to the same schema.</li>
<li>Swap mocks for real endpoints as they land, testing continuously so the contract holds.</li>
<li>Keep talking. The schema is a living document, not a stone tablet.</li>
</ol>

<h3 class="relative group">The catches
    <div id="the-catches" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#the-catches" aria-label="Anchor">#</a>
    </span>
    
</h3>
<p>It isn&rsquo;t free. Writing a thorough schema upfront takes real time. When requirements change, the schema has to change first, and the ripples hit both teams. And everyone needs at least a working familiarity with OpenAPI and the tooling around it.</p>
<p>Even so, I&rsquo;ve never seen the upfront cost lose to the integration chaos it prevents. Frontend starts on day one, and the arguments happen over a document instead of over broken builds.</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2023/2023-10-08-open-api/featured.jpg" medium="image" type="image/jpeg" />
    </item>
  </channel>
</rss>
