# Overview — Developers

**Audience:** Engineers installing and evaluating `@x12i/api-simulator`.  
**Related:** [Behaviors](../01-behaviors/developers/BOOK.md) · [Package simulators](../03-package-simulators/developers/BOOK.md)

---

## 1. What it is

Core TypeScript framework for building simulated API services.

Each endpoint defines **exactly one** behavior:

1. `fixed` — always return the configured response.
2. `relative` — render a configured JSON response using values from the request and API-local data.
3. `simulation` — run a function that receives the matched request and returns a response.

The core is transport-agnostic. It can be called directly from tests, wrapped by Fastify/Express, or exposed through the included Node.js HTTP adapter.

**Data and metadata:** this package does **not** load fixtures from disk, MongoDB, Memorix, or HTTP. Consumers pass an in-memory `SimulatorDefinition` (`api.data` + endpoints). Optional helpers (`createStore`, OpenAPI) still take data you supply. Product-owned **package simulators** ship their own logic, data, and (when needed) Memorix fixtures.

---

## 2. Install

```bash
npm install @x12i/api-simulator
```

Requires Node.js 20+.

For agents and assembled use-case / book markdown packs (devDependency only):

```bash
npm i -D @x12i/api-simulator-docs
```

Then: `npx api-simulator-docs list-use-cases` · `npx api-simulator-docs use-case orient-simulator`.

---

## 3. Minimal example

```ts
import { createApiSimulator } from '@x12i/api-simulator';

const simulator = createApiSimulator({
  apis: [
    {
      id: 'objects-api',
      basePath: '/api/v1',
      data: {
        children: [
          {
            id: 'child-1',
            parentId: '{{request.params.parentId}}'
          },
          {
            id: 'child-2',
            parentId: '{{request.params.parentId}}'
          }
        ]
      },
      endpoints: [
        {
          id: 'health',
          method: 'GET',
          path: '/health',
          behavior: {
            type: 'fixed',
            response: {
              status: 200,
              body: { status: 'ok' }
            }
          }
        },
        {
          id: 'list-children',
          method: 'GET',
          path: '/parents/:parentId/children',
          behavior: {
            type: 'relative',
            response: {
              body: {
                parentId: '{{request.params.parentId}}',
                items: '{{data.children}}'
              }
            }
          }
        },
        {
          id: 'calculate-score',
          method: 'POST',
          path: '/score',
          behavior: {
            type: 'simulation',
            handler: ({ request }) => {
              const values = (request.body as { values: number[] }).values;
              return {
                body: {
                  score: values.reduce((sum, value) => sum + value, 0)
                }
              };
            }
          }
        }
      ]
    }
  ]
});
```

---

## 4. Where to go next

- Try the **Playground** app (anonymous, ~30-second first dispatch).
- Author projects in **Studio** (local-first).
- Follow [`examples/library-demo/TUTORIAL.md`](../../../examples/library-demo/TUTORIAL.md) for a guided REST walkthrough.
- Or [`examples/flowstate-simulator/TUTORIAL.md`](../../../examples/flowstate-simulator/TUTORIAL.md) to compose with `@x12i/static-memorix`.
- Use cases: `orient-simulator`, `define-three-behaviors`, `ship-package-simulator` (`npm i -D @x12i/api-simulator-docs`).