Skip to main content
Get up and running with Apicentric by creating a simple mock API. You’ll define an API, start the simulator, and send requests.

​
Prerequisites

Make sure you have Apicentric installed. If not, follow the installation guide. 
apicentric --version

​
Create your first mock API

Let’s build a simple user management API with CRUD operations.
1

Create a service definition

Create a file named users-api.yaml:
users-api.yaml
name: Users API
version: "1.0"
description: Simple user management API

server:
  port: 8080
  base_path: /api/v1

fixtures:
  users:
    - id: 1
      name: "Alice Johnson"
      email: "[email protected]"
      role: "admin"
    - id: 2
      name: "Bob Smith"
      email: "[email protected]"
      role: "user"

endpoints:
  - method: GET
    path: /users
    description: List all users
    responses:
      200:
        content_type: application/json
        body: |
          {
            "users": [
              {{#each fixtures.users}}
              {
                "id": {{id}},
                "name": "{{name}}",
                "email": "{{email}}",
                "role": "{{role}}"
              }{{#unless @last}},{{/unless}}
              {{/each}}
            ],
            "total": {{fixtures.users.length}}
          }
  
  - method: GET
    path: /users/{id}
    description: Get a user by ID
    responses:
      200:
        content_type: application/json
        body: |
          {
            "id": {{params.id}},
            "name": "{{#find fixtures.users "id" params.id}}{{name}}{{/find}}",
            "email": "{{#find fixtures.users "id" params.id}}{{email}}{{/find}}",
            "role": "{{#find fixtures.users "id" params.id}}{{role}}{{/find}}"
          }
  
  - method: POST
    path: /users
    description: Create a new user
    request_body:
      content_type: application/json
      schema: |
        {
          "name": "string",
          "email": "string",
          "role": "string"
        }
    responses:
      201:
        content_type: application/json
        body: |
          {
            "id": {{faker "datatype.number" min=100 max=999}},
            "name": "{{request.body.name}}",
            "email": "{{request.body.email}}",
            "role": "{{request.body.role}}",
            "created_at": "{{now}}"
          }
This YAML defines three endpoints: list users, get a user by ID, and create a user.
2

Start the simulator

Run the simulator with your service definition:
apicentric simulator start --services-dir .
You should see output like:
[INFO] Loading service definitions from current directory
[INFO] Starting Users API on http://localhost:8080
[INFO] Available endpoints:
       GET  http://localhost:8080/api/v1/users
       GET  http://localhost:8080/api/v1/users/{id}
       POST http://localhost:8080/api/v1/users
[INFO] Simulator running. Press Ctrl+C to stop.
The simulator watches for file changes. Edit users-api.yaml and your changes will reload automatically!
3

Test your API

Open a new terminal and send some requests:List all users:
curl http://localhost:8080/api/v1/users
Response:
{
  "users": [
    {
      "id": 1,
      "name": "Alice Johnson",
      "email": "[email protected]",
      "role": "admin"
    },
    {
      "id": 2,
      "name": "Bob Smith",
      "email": "[email protected]",
      "role": "user"
    }
  ],
  "total": 2
}
Get a specific user:
curl http://localhost:8080/api/v1/users/1
Create a new user:
curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Charlie Brown",
    "email": "[email protected]",
    "role": "user"
  }'
Response:
{
  "id": 742,
  "name": "Charlie Brown",
  "email": "[email protected]",
  "role": "user",
  "created_at": "2026-03-01T12:34:56Z"
}
Notice how the response uses dynamic data: random ID from Faker and current timestamp from the now helper.
4

View request logs

Check the logs to see all requests:
apicentric simulator logs --service users-api
Or use the interactive TUI:
apicentric tui
The TUI provides a real-time dashboard with service status, logs, and filtering options.

​
What you learned

You just:
  • ✅ Created a service definition with fixtures and endpoints
  • ✅ Started the API simulator
  • ✅ Tested your mock API with curl
  • ✅ Used Handlebars templates for dynamic responses
  • ✅ Leveraged built-in helpers (faker, now, find, each)

​
Next steps

Core concepts

Learn about service definitions, fixtures, and scenarios

Create mock APIs

Build more complex APIs with validation and conditional responses

Generate code

Generate TypeScript types and React Query hooks from your API

Browse examples

Explore real-world examples like e-commerce and IoT

​
Common next tasks

Add schema validation to ensure requests have required fields:
request_body:
  content_type: application/json
  schema: |
    {
      "name": "string",
      "email": "string"
    }
responses:
  422:
    condition: "{{not request.body.name}}"
    content_type: application/json
    body: |
      {
        "error": "Validation failed",
        "details": ["Name is required"]
      }
See the request validation guide for more.
Simulate different API states (latency, errors, maintenance):
scenarios:
  - name: "slow_network"
    description: "Simulate slow network"
    delay_ms: 2000
  
  - name: "server_error"
    description: "Simulate server error"
    response:
      status: 500
      body: |
        {"error": "Internal server error"}
Activate with:
apicentric simulator set-scenario --scenario slow_network
Learn more in the scenarios guide.
Package your API for easy sharing:
apicentric simulator dockerize --file users-api.yaml --output ./users-api-docker
cd users-api-docker
docker build -t users-api .
docker run -p 8080:8080 users-api
See the Docker deployment guide.
Generate client code from your API:
apicentric simulator generate-types --file users-api.yaml --output ./types.ts
See the code generation guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us