APImposter 🎭

A small, flexible API mock service designed with microservice environments in mind.

---

What is APImposter?

APImposter is an easy-to-use service built with Spring Boot, enabling quick mocking of API responses from various systems. It allows you to organize your mock data in YAML files.

---

Key Features

• Structured Mock Data: Organize your mock data in YAML files.
• Automatic URL Mapping: Automatically generates URL structure based on your folder hierarchy and YAML file names.
• Hot Reloading: Automatically reloads mock data files when they are changed.
• Dynamic Responses and Global Placeholders: Supports dynamic values in responses based on URL parameters and you can define global placeholders to reuse values across multiple responses and systems.
• Conditional Responses: Return different mock responses based on request data (headers, query, body, or path).
• Swagger UI: Automatically generated Swagger UI from YAML files.
• Quick Setup: Easy installation and configuration.

---

Mocks Structure

YAML defined mocks are stored in a directory defined in application.properties. You can organize them in nested folders like this:

/mocks/
├── globals.yaml
├── system1/
│   ├── users.yaml
│   └── program.yaml
└── another-system/
    ├── endpoint1.yaml
    └── subdir/
        └── endpoint2.yaml

Example YAML files:

# globals.yaml
globals:
  currentUserId: "user-123"

# system1/users.yaml
- method: "GET"
  path: "/{id}"
  response:
    status: 200
    headers:
      Content-Type: "application/json"
    body:
      id: "{id}"
      name: "Example User"

# system1/program.yaml
- method: "GET"
  path: "/"
  delay: 500
  response:
    status: 200
    headers:
      Content-Type: "application/json"
    body:
      programId: 12345
      globalUserId: "{globals.currentUserId}"

---

Example Requests and Responses

YAML file	Request	Response
mocks/system1/users.yaml	GET /<prefix>/system1/users/123	{ "id": "123", "name": "Example User" }
mocks/system1/program.yaml	GET /<prefix>/system1/program	{ "programId": 12345, "globalUserId": "user-123" }
mocks/another-system/subdir/endpoint2	GET /<prefix>/another-system/subdir/endpoint2/...	(defined response JSON)

Dynamic placeholders in responses ({id}) and global placeholders ({globals.currentUserId}) are automatically replaced with actual URL parameters or globally defined values.

Folders in the YAML file structure become part of the URL path automatically.

---

Conditional Responses

APImposter supports conditional responses, allowing different mock responses to be returned based on request values — like query parameters, headers, path variables, or body fields.

This is useful for simulating realistic API behavior, such as authentication, filtering, or alternate success/error outcomes.

Supported condition types:

• path: matches against path variables
• query: matches query parameters (?filter=active)
• headers: matches HTTP headers (case-insensitive)
• body: matches top-level JSON body fields (for POST/PUT)

Example: conditionals by path

- method: "GET"
  path: "/users/{id}"
  conditionalResponses:
    - conditions:
        path:
          id: "1"
      response:
        status: 200
        headers:
          Content-Type: application/json
        body:
          id: 1
          name: "Lennart"
    - conditions:
        path:
          id: "2"
      response:
        status: 200
        headers:
          Content-Type: application/json
        body:
          id: 2
          name: "Kurre"
  response:
    status: 404
    headers:
      Content-Type: application/json
    body:
      error: "User not found"

Example: conditionals by header

- method: "GET"
  path: "/secure"
  conditionalResponses:
    - conditions:
        headers:
          authorization: "Bearer abc123"
      response:
        status: 200
        headers:
          Content-Type: application/json
        body:
          message: "Access granted"
  response:
    status: 401
    headers:
      Content-Type: application/json
    body:
      error: "Unauthorized"

Example: conditionals by query parameter

- method: "GET"
  path: "/products"
  conditionalResponses:
    - conditions:
        query:
          category: "books"
      response:
        status: 200
        headers: { Content-Type: "application/json" }
        body:
          products:
            - id: "b1"
              name: "Data Structures and Algorithms in Java"
    - conditions:
        query:
          category: "tech"
      response:
        status: 200
        headers: { Content-Type: "application/json" }
        body:
          products:
            - id: "t1"
              name: "Mechanical Keyboard"
  response:
    status: 200
    headers: { Content-Type: "application/json" }
    body:
      products: []

Example: conditionals by request body

- method: "POST"
  path: "/login"
  conditionalResponses:
    - conditions:
        body:
          username: "admin"
          password: "secret"
      response:
        status: 200
        headers:
          Content-Type: application/json
        body:
          token: "abc123"
  response:
    status: 403
    headers:
      Content-Type: application/json
    body:
      error: "Invalid credentials"

Testing with curl

curl http://localhost:8080/mocks/users/1

curl -H "Authorization: Bearer abc123" http://localhost:8080/mocks/secure

curl "http://localhost:8080/mocks/products?category=books"

curl -X POST http://localhost:8080/mocks/login \
     -H "Content-Type: application/json" \
     -d '{"username": "admin", "password": "secret"}'

Conditions are evaluated in order, and the first matching block wins. If no condition matches, the fallback response: is used.

---

Configuration

In application.properties you can configure the following properties:

• mock.file-path: The path to the directory containing your mock data YAML files.
• mock.reload-interval-ms: The interval in milliseconds at which the service checks for changes in the mock data files.
• mock.base-path: The base path for the mock service. This is prepended to all generated URLs. Default is /mocks.
• mock.default-delay-ms: The default delay in milliseconds for responses. This can be overridden in the YAML files.

---

Swagger UI

OpenAPI Specification is generated from the mock data YAML files and can be accessed via Swagger UI. You will find it at:

http://localhost:8080/swagger

---

Quick Start

Clone the project and run it simply with:

./mvnw spring-boot:run

or with Docker:

docker-compose up

---

🎭 Good luck and happy mocking! 🎭