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

A developer proposes the API notebook pattern: keeping explanation, runnable requests, expected responses, assertions, and workflow notes in small files inside the repository. This single artifact serves documentation, testing, CI, and coding agents, reducing fragmentation and drift across READMEs, GUI collections, OpenAPI files, shell tests, and chat prompts. The pattern ensures that when API behavior changes, the contract updates in the same pull request, making reviews clearer and agents more reliable.

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: 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: 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. 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. 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: 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 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: 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. I am building Reqbook https://markapidown.net/ , 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: This pattern is not the right default for every team. A traditional API client or hosted platform may be a better choice when: 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. Do not migrate an entire API at once. Pick one flow that already creates confusion: Then: 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.