An introduction to spec-driven API development

Historically, API design has been mainly implementation-driven (also called code-first). Nothing faster than quickly prototyping a few endpoints together before even thinking about putting together an API specification. More specs, more problems. Or is it?

The answer is a resounding no. As teams scale and products grow more complex, a code-first approach to API development tends to become a liability. APIs become inconsistent. Documentation lags behind. Onboarding new developers takes longer. Partners and consumers face undocumented breaking changes.

Spec-driven development flips that model. You define the contract first — what endpoints exist, what they accept, what they return — and implementation follows from that definition. This article walks through what that looks like in practice, why it matters, and how to get started.

What is spec-driven development?

Spec-driven development (also called design-first or contract-first API development) means writing an API specification before writing any server code. The specification becomes the source of truth for everything that follows: documentation, mocks, tests, SDKs, and the implementation itself.

The most widely used format for REST API specifications is OpenAPI (formerly Swagger). An OpenAPI document is a YAML or JSON file that describes your API's endpoints, parameters, request/response schemas, authentication methods, and error formats.

Here is a minimal example:

openapi: 3.0.3
info:
  title: Payments API
  version: 1.0.0
paths:
  /payments:
    post:
      summary: Create a payment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
      responses:
        '201':
          description: Payment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
components:
  schemas:
    CreatePaymentRequest:
      type: object
      required: [amount, currency, source]
      properties:
        amount:
          type: integer
        currency:
          type: string
        source:
          type: string
    Payment:
      type: object
      properties:
        id:
          type: string
        amount:
          type: integer
        currency:
          type: string
        status:
          type: string

This single file is enough to generate interactive documentation, spin up a mock server, run contract tests, and validate implementation.

Why code-first creates problems at scale

Code-first is fast at the start. You write a route handler, it works, you move on. The problems surface later.

Inconsistency. When multiple developers write endpoints without a shared contract, the API accumulates inconsistencies. Some endpoints return id, others return uuid. Some use camelCase, others use snake_case. Error shapes vary by endpoint. None of this is intentional — it's the natural result of parallel development without coordination.

Documentation drift. With code-first, documentation is typically generated after the fact or written manually. Either way, it tends to fall behind. Breaking changes get shipped without documentation updates. Consumers discover changes by hitting errors in production.

Slow consumer onboarding. Undocumented or inconsistently documented APIs slow down everyone who integrates with them. Partners spend time reverse-engineering behavior that should be specified. Support load increases.

Testing after the fact. When tests are written after implementation, they tend to test what the code does rather than what it should do. Edge cases get missed. Contract testing becomes impossible because there is no contract to test against.

How spec-driven development solves this

Defining the contract first changes the development dynamic in several ways.

Design review becomes possible. When the spec is written before code, team members and stakeholders can review the API design before a line of implementation is written. You can catch naming issues, missing fields, and design inconsistencies at the cheapest possible moment.

Mocks enable parallel development. Once the spec exists, tools like Prism can generate a mock server from it in seconds. Frontend teams and API consumers can build against the mock while backend implementation is in progress. There is no blocking dependency.

Contract tests catch regressions early. Tools like Dredd or Schemathesis can run automated tests against your implementation and verify it matches the spec. If implementation drifts from the contract, tests fail. This keeps documentation accurate by definition.

SDK and documentation generation. An accurate OpenAPI spec can generate client SDKs in multiple languages, interactive API documentation (Swagger UI, Redoc), and Postman collections — all from the same source of truth.

The spec-driven workflow in practice

A typical spec-driven workflow looks like this:

1. Draft the spec. Write the OpenAPI document for the feature or API you are building. Focus on the contract: what are the endpoints, what do they accept, what do they return, what errors can they produce.

2. Review the spec. Conduct a design review with stakeholders. This is the cheapest time to make changes. Update the spec based on feedback.

3. Spin up a mock. Use Prism or a similar tool to generate a mock server from the spec. Share the mock with consumers so they can begin integration work.

4. Implement against the spec. Write the server implementation. The spec is the acceptance criteria.

5. Run contract tests. Verify the implementation matches the spec using contract testing tools. Fix any drift.

6. Publish documentation. Because documentation is generated from the spec, it is accurate by definition. Publish it as part of the release process.

Tooling

Several tools make spec-driven development practical:

Stoplight Studio — A GUI editor for OpenAPI specifications. Useful for teams that prefer visual editing over writing YAML directly.

Prism — Generates a mock server from an OpenAPI spec. Supports response validation and proxying.

Dredd — Runs HTTP tests against your API and verifies responses match the spec.

Schemathesis — Property-based testing tool that generates test cases from OpenAPI specs and finds edge cases automatically.

Redoc / Swagger UI — Generate interactive API documentation from OpenAPI specs.

Portman — Converts OpenAPI specs to Postman collections and adds contract tests automatically.

Spec-driven development pays off most when you're integrating across multiple platforms. Apideck's HRIS API is built on this principle — a single OpenAPI spec covering Workday, BambooHR, Personio, and dozens of other HR systems, so your team writes integration code once against a consistent contract.