---
name: Mockaton
description: Generates and serves mock HTTP APIs. Use when creating, editing, or reasoning about mock endpoints.
user-invocable: false
---
## Basic Usage
```sh
npx mockaton --port 2020 my-mocks-dir/
```

Mockaton will serve the files on the given directory. It's a file-system based router, so
filenames can have dynamic parameters. Also, filenames can have comments, which are
anything within parentheses, this way each route can have different mock file variants.
Similarly, each route can have different response status code variants.


| Route | Filename | Description |
| -----| -----| ---|
| /api/company/123 | api/company/[id].GET.200.ts | `[id]` is a dynamic parameter. `.ts`, and `.js` are sent as JSON by default |
| /media/avatar.png | media/avatar.png | Statics assets don't need the above extension |
| /api/login | api/login(invalid attempt).POST.401.ts | **Anything within parenthesis is a comment**, they are ignored when routing |
| /api/login | api/login(default).GET.200.ts | `(default)` is a special comment; otherwise, the first mock variant in alphabetical order wins  |
| /api/login | api/login(locked out user).POST.423.json | `.json` is allowed too |


## Docs
- [Configuration: CLI and mockaton.config.js](https://mockaton.com/config).
- [Programmatic API](https://mockaton.com/api), in which
  you can delay a route, select a different mock file, such as a 500 error, among other options.



## Installation ([more options  ↗](https://mockaton.com/installation))
```sh
npm install mockaton
```

## How to create mocks?
Write it to your mocks directory. `.ts` files are served as JSON by default.
```sh
mkdir -p my-mocks-dir/api
echo "export default { name: 'John' }" > my-mocks-dir/api/user.GET.200.ts
```

### Example A: JSON
For JSON responses, use TypeScript (or JS), and `export default` an Object, Array, or 
String.

- **Route:** /api/company/123
- **Filename:** api/company/[id].GET.200.ts

```ts
interface Company {
  name: string
}

export default {
  name: 'Acme, Inc.'
} satisfies Company
```

### Example B: Non-JSON
- **Route:** /api/company/123
- **Filename:** api/company/[id].GET.200.xml

```xml
<company>
 <name>Acme, Inc.</name>
</company>
```

### Example C: [Function Mocks](https://mockaton.com/function-mocks)
With a function mock you can do pretty much anything you could do with a normal backend handler.
For example, you can handle complex logic, URL parsing, saving to a database, etc.

- **Route:** /api/company/abc/user/999
- **Filename:** api/company/[companyId]/user/[userId].GET.200.ts

```ts
import { IncomingMessage, OutgoingMessage } from 'node:http'
import { parseSegments } from 'mockaton'

export default async function (req: IncomingMessage, response: OutgoingMessage) {
  const { companyId, userId } = parseSegments(req.url, import.meta.filename)
  const foo = await getFoo()
  return JSON.stringify({
    foo,
    companyId,
    userId,
    name: 'Acme, Inc.'
  })
}
```