The API Notebook Pattern: One File for Docs, Tests, and Agent Context

Most API workflow pain is not about sending the request.

It is about everything around the request.

The docs live in a README. The real payload shape lives in the backend. The manual test lives in a GUI collection. The CI check lives in a shell script. Then a coding agent enters the project and has to reconstruct the same route, auth rule, and expected response from scattered clues.

That fragmentation makes drift the default.

A useful way to reduce it is the API notebook pattern: keep the explanation, runnable request, expected response, assertions, and workflow notes in small files inside the repository.

One artifact can then serve four audiences:

• developers can read it,
• reviewers can diff it,
• CI can execute it,
• coding agents can use it as bounded context.

What is an API notebook?

An API notebook is not a giant specification dump. It is also more than a saved request.

It is a small, reviewable file for one endpoint or product flow. It should answer the questions developers repeatedly ask during implementation:

• What is this endpoint for?
• What request should I send?
• Which variables or credentials does it need?
• What response counts as correct?
• What should fail the check?
• Which workflow depends on this behavior?

A minimal notebook might look like this:

# Create checkout session

Creates a hosted checkout session for an open cart.

## Request

```http
POST {{baseUrl}}/checkout/sessions
Content-Type: application/json
Authorization: Bearer {{authToken}}

{
  "cartId": "{{cartId}}",
  "successUrl": "https://example.test/success"
}
```

## Expected response

```http
HTTP/1.1 201 Created

{
  "id": "{{checkoutSessionId}}",
  "cartId": "{{cartId}}",
  "status": "ready"
}
```

## Assertions

- status: 201
- body.id: exists
- body.cartId: equals "{{cartId}}"
- body.status: equals ready

## Notes

- Requires an authenticated customer session.
- Returns 409 when the cart is already checked out.

It is intentionally boring.

But it gives a reviewer enough context to understand the contract, gives CI enough structure to run a check, and gives a coding agent fewer reasons to guess.

Why existing API workflows drift

Most teams already have several useful API artifacts. The problem is that each one becomes a separate source of truth.

Artifact	What it does well	Where drift appears
README example	Easy to scan	Usually not executed
GUI collection	Good for exploration	Hard to review in pull requests
OpenAPI file	Broad schema coverage	Often too broad for one implementation task
Shell smoke test	Fast in CI	Too terse to explain the contract
Chat prompt	Useful for one task	Quickly becomes stale

The handler changes first. Documentation catches up later. The collection may only exist in one workspace. The test checks the happy path but does not explain why the response changed.

An API notebook reduces the number of places that must stay synchronized.

Put the contract in the pull request

The biggest benefit is not the command line. It is the review loop.

When API behavior changes intentionally, the contract should change in the same pull request:

 ## Expected response
 {
   "id": "{{userId}}",
   "email": "{{email}}",
-  "status": "pending_verification"
+  "status": "active"
 }

That small diff explains the behavior change more directly than many route-handler diffs.

It also lets the review process ask better questions:

• Is this response change intentional?
• Which flow depends on the old value?
• Were the failure cases updated?
• Does CI execute this contract?
• Will a coding agent read the new behavior before editing related code?

Endpoint files and flow files solve different problems

One endpoint file should own one contract.

A flow file should describe a product journey that connects several contracts:

1. Create cart
   - Capture: response.body.id as cartId
2. Add item
   - Inject: cartId, sku, quantity
3. Create checkout session
   - Inject: cartId
   - Capture: response.body.id as checkoutSessionId
4. Get checkout session
   - Inject: checkoutSessionId

This is easier to reason about than a disconnected list of request tabs because the value movement is explicit.

A repository can stay simple:

api-docs/
  reqbook.md
  _shared/
    env.md
  apis/
    auth/post-login.md
    users/post-create-user.md
    checkout/post-create-session.md
  flows/
    signup-login-profile.md
    cart-checkout.md

Why this helps coding agents

Coding agents are good at reading files. They are less reliable when they must infer workflow state from several systems.

If the API contract is split across source code, documentation, collection tabs, environment notes, and old prompts, the agent spends context reconstructing the behavior before it can make the actual change.

A notebook gives it a bounded artifact containing:

• request method, URL, headers, and body,
• variables and environment names,
• expected status and response shape,
• assertions that define success,
• business rules and failure cases,
• nearby flow context.

This does not make the agent smarter. It makes the task less ambiguous.

The same principle applies even if you do not use AI tools: stable, executable examples are easier for every developer to trust.

Where Reqbook fits

I am building Reqbook, so I am biased, but it is one implementation of this pattern.

Reqbook keeps API docs, requests, tests, flows, and coding-agent context as runnable Markdown in the repository. Its browser UI, VS Code extension, CLI, CI commands, and agent tooling operate on the same files.

A basic loop looks like this:

rqb validate api-docs/
rqb exec api-docs/apis/checkout/post-create-session.md --env dev
rqb flow api-docs/flows/cart-checkout.md --env dev

The product is less important than the workflow shape:

1. Read the contract before changing implementation code.
2. Update the contract when behavior changes.
3. Execute the endpoint or flow locally.
4. Run the same artifact in CI.
5. Keep it available to reviewers and coding agents.

When the notebook pattern is not a good fit

This pattern is not the right default for every team.

A traditional API client or hosted platform may be a better choice when:

• most work is manual, GUI-heavy exploration,
• hosted collaboration and governance matter more than repo ownership,
• the API is small enough that a few smoke tests are sufficient,
• nobody needs the test files to double as documentation or agent context.

There is also a maintenance cost. A useful notebook requires more discipline than saving a request tab.

In return, you get a contract that is readable, reviewable, executable, and reusable.

Start with one workflow

Do not migrate an entire API at once.

Pick one flow that already creates confusion:

• signup, login, and profile fetch,
• cart creation, item addition, and checkout,
• workspace creation and member invitation,
• webhook registration and callback verification.

Then:

1. Add the endpoint contracts.
2. Record expected responses and basic assertions.
3. Keep secrets outside committed files.
4. Run the workflow locally.
5. Add the stable path to CI.

The useful standard is simple:

A developer can read it. A reviewer can diff it. CI can run it. A coding agent can use it before changing code.

That is what makes an API notebook more than documentation.