AI-Ready Docs

07 / ASD

API Specification Document

How do different parts of the system communicate?

The API Specification Document defines the communication contracts between systems or application layers. It specifies how requests are made, what information they contain, what responses are returned, how errors are represented, and what rules govern the communication.

Layer
Engineering
Primary purpose
Define how systems or application layers communicate.
Used by
Product / Design / Engineering / AI
On this page
  1. 01What is it?
  2. 02Why do we need it?
  3. 03When do we create it?
  4. 04Who benefits from it?
  5. 05What does it contain?
  6. 06What does it NOT contain?
  7. 07What does an API specification look like?
  8. 08API specification elements
  9. 09How does AI use it?
  10. 10How does it connect to other documents?
  11. 11Example
  12. 12Template
  13. 13Common mistakes
01

What is it?

The API Specification Document defines how different parts of a product communicate. It makes the communication contract explicit by defining requests, responses, validation, errors, authentication requirements, and other behavior that must be consistent between communicating systems.

  • FSD

    What

  • BRD

    Rules

  • UFD

    Behavior

  • DSD

    Experience

  • DDD

    Data

  • ASD

    Communication

02

Why do we need it?

A feature can be clearly defined and the required data can be modeled, but implementation still needs an explicit contract for how information moves between systems.

Without ASD

Feature
Data model
Developer infers communication
Different interpretations

With ASD

Feature
Data model
Defined communication contract
Implementation

The purpose is to remove ambiguity from communication. The problem is undocumented communication decisions, not that developers cannot design APIs.

03

When do we create it?

The ASD is created once the product behavior and required data are understood well enough to define how the relevant systems or application layers need to communicate.

This is an information relationship, not a rigid waterfall. API design can expose missing data, business-rule, or behavioral decisions that need clarification.

PRD
FSD
BRD
UFD
DSD
DDD
ASD
TAD
Implementation
04

Who benefits from it?

  • Product

    Uses it to understand how product capabilities exchange information.

  • Design

    Uses it to understand what information and states the interface can depend on.

  • Engineering

    Uses it as the explicit communication contract between clients, services, and other systems.

  • AI agent

    Uses it to implement communication consistently without inventing request or response behavior.

05

What does it contain?

These are the fields an API specification can define.

  1. 01

    Endpoint

    The defined communication point.

  2. 02

    Method / Operation

    What operation the endpoint performs.

  3. 03

    Purpose

    Why the endpoint exists.

  4. 04

    Authentication / Authorization

    What access requirements apply.

  5. 05

    Request

    What information the caller provides.

  6. 06

    Parameters

    Path, query, header, or other defined parameters.

  7. 07

    Request Body

    The structured information sent when applicable.

  8. 08

    Response

    What information the system returns.

  9. 09

    Status / Outcome

    How success and relevant outcomes are represented.

  10. 10

    Validation

    What request conditions must be satisfied.

  11. 11

    Errors

    How expected failures are represented.

  12. 12

    Side Effects

    Other documented changes triggered by the operation.

  13. 13

    Dependencies

    Other systems, services, or data the operation relies on when relevant.

  14. 14

    Idempotency / Retry Behavior

    Requirements that affect repeated requests when applicable.

Not every endpoint needs every field — only document what is relevant to the operation.

06

What does it NOT contain?

  • Product vision
  • Feature scope
  • Complete business rules
  • Complete user journeys
  • UI layouts
  • UI visual design
  • Database schema
  • Overall application architecture
  • Frontend component structure
  • Backend implementation
  • Deployment infrastructure
  • Source code

DDD

What data exists?

ASD

How does information move?

TAD

How is the technical system structured?

07

What does an API specification look like?

API specification

API ID
API-014
Operation
Create Project

Purpose

Creates a project using the information defined by the product requirements and data model.

Method
POST
Path
/projects
Authentication
Authenticated user

Request

The request contains the information required to create a project.

  • Project name
  • Organization reference

Validation

The request must satisfy the documented business and data requirements.

Success response

The system returns the result of the project creation operation.

Errors

  • Validation failure
  • Unauthorized request
  • Other documented failure conditions

Side effects

A project record is created.

Conceptual communication path

Client
API
Service

This is a methodology example, not a production API contract — exact field names, status codes, and framework details are not defined here.

08

API specification elements

  1. 01

    Endpoint

    A defined communication point.

  2. 02

    Operation

    The action performed through the endpoint.

  3. 03

    Request

    The information provided by the caller.

  4. 04

    Response

    The information returned by the system.

  5. 05

    Parameter

    A defined value used to control or identify a request.

  6. 06

    Validation

    Conditions that incoming information must satisfy.

  7. 07

    Error

    A defined failure condition and its response.

  8. 08

    Authentication

    How the caller's identity is established.

  9. 09

    Authorization

    What access the caller has.

  10. 10

    Side Effect

    A documented change caused by the operation beyond the immediate response.

  11. 11

    Idempotency

    Whether repeating the same operation produces the same intended result when relevant.

09

How does AI use it?

The ASD gives the AI agent an explicit communication contract. It tells the agent what operations exist, what information they accept, what they return, what validation applies, and how expected failures should behave.

ASD
Communication contract

AI understands

  • Which operations exist
  • How they are invoked
  • What information is required
  • What responses are expected
  • What validation applies
  • What errors must be handled
  • What side effects occur
  • Which access requirements apply

Without ASD

Feature + DDD
AI invents API behavior

With ASD

Feature + DDD + ASD
AI implements defined communication

AI should not invent an endpoint contract simply because it can infer one. If required communication decisions are missing, surface a specification gap.

Specification gap

Feature

Create Project

The feature requires project creation, but the documentation does not define whether the client communicates with the project service directly or through another documented interface.

Implementation paused.

Decision required

Define the communication contract before implementation.

10

How does it connect to other documents?

FSD

Create Project

“What capability exists?”

BRD

Project creation rules

“What conditions apply?”

UFD

Create Project flow

“How does the behavior progress?”

DSD

Create Project interface

“How should the experience be represented?”

DDD

Project data

“What information must be stored?”

ASD

Create Project operation

“How is information communicated?”

TAD

Technical structure

“How is the system organized?”

The ASD turns defined product behavior and data requirements into explicit communication contracts.

Feature

FEAT-004

Rule

RULE-001

Flow

FLOW-001

Screen

SCREEN-009

Entity

ENTITY-001

API

API-014

11

Example

Feature concept

Create a Project

ASD perspective

The project creation operation defines how the client communicates the required information and receives the result.

PRD

Why

Users need a way to organize their work into projects.

FSD

What

Users can create a project.

BRD

Rules

Project creation follows defined business rules.

UFD

Behavior

The user moves through the project creation journey and reaches a defined outcome.

DSD

Experience

The interface represents the journey through defined screens, states, interactions, responsive behavior, and feedback.

DDD

Data

The system stores the project information and its relationship to the relevant organization.

ASD

Communication

The project creation operation defines how the client communicates the required information and receives the result.

TAD

Structure

How the capability is technically structured.

DR

Order

When it should be implemented.

AI Instructions

Implementation

How the agent should implement the task.

12

ASD Template

asd-template.md

# API Specification Document

## 01. API Overview

## 02. Endpoint Specification

### API ID

### Operation

### Purpose

### Method

### Path

### Authentication

### Authorization

### Request

### Parameters

### Request Body

### Validation

### Success Response

### Error Responses

### Side Effects

### Dependencies

### Idempotency / Retry Behavior

---

## 03. Shared Data Structures

## 04. Authentication / Authorization

## 05. Error Model

## 06. Open Communication Decisions
13

Common mistakes

  • Defining endpoints without understanding the feature they support.
  • Duplicating the entire database schema inside every API specification.
  • Leaving request and response behavior implicit.
  • Leaving validation behavior undefined.
  • Documenting only successful responses.
  • Ignoring authentication or authorization requirements.
  • Leaving important error behavior unspecified.
  • Mixing API contracts with application architecture.
  • Mixing API contracts with database implementation.
  • Creating endpoints because they "might be useful later" without a documented requirement.
  • Letting AI invent request or response structures that were never specified.
  • Assuming an API specification is the same thing as the backend implementation.