Skip to main content
Service definition files use YAML format to describe your API services, including endpoints, request/response structures, and simulation behaviors.

Location

By default, service definition files are stored in the directory specified by simulator.services_dir in your apicentric.json (default: services/).

File naming

You can name your service files anything you want, as long as they have a .yaml or .yml extension. Apicentric automatically discovers and loads all YAML files in the services directory. Examples:
  • user-service.yaml
  • payment-api.yaml
  • inventory.yml

Basic structure

name: Demo API
version: "1.0"
description: A demo API for the walkthrough
server:
  port: 9005
  base_path: /api/v1

endpoints:
  - method: GET
    path: /users
    responses:
      200:
        content_type: application/json
        body: |
          [
            {"id": 1, "name": "Alice"},
            {"id": 2, "name": "Bob"}
          ]

Service metadata

Define basic information about your service.
name
string
required
The name of your service. This appears in logs and the admin interface.
version
string
Semantic version of your service definition.Example: "1.0", "2.1.0"
description
string
Human-readable description of what this service does.

Server configuration

Configure how your service listens for requests.
server
object
Server configuration for the service
server.port
number
Port number to listen on. If not specified, Apicentric automatically assigns a port from the configured range.
Ports below 1024 require elevated permissions and will generate a validation warning.
server.base_path
string
required
Base path prefix for all endpoints. Must start with /.Example: /api/v1, /, /services
server.proxy_base_url
string
Base URL to proxy requests when no local endpoint matches. Useful for partial mocking.Example: http://production-api.example.com
server.record_unknown
boolean
When enabled with proxy_base_url, automatically records proxied responses for later use.Default: false
server.cors
object
CORS configuration for cross-origin requests.
server.cors.enabled
boolean
required
Enable CORS support.
server.cors.origins
array
required
List of allowed origins.Example: ["http://localhost:3000", "https://app.example.com"]
server.cors.methods
array
Allowed HTTP methods.Example: ["GET", "POST", "PUT", "DELETE"]
server.cors.headers
array
Allowed request headers.Example: ["Content-Type", "Authorization"]

Data models

Define reusable JSON schemas for request and response validation.
models
object
Map of model names to JSON Schema definitions.
models:
  User:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      email:
        type: string
        format: email
    required:
      - id
      - name

Fixtures

Define reusable test data that can be referenced in responses.
fixtures
object
Map of fixture names to data objects.
fixtures:
  users:
    - id: 1
      name: Alice
    - id: 2
      name: Bob
You can reference fixtures in responses using Handlebars: {{fixture "users"}}

Bucket storage

Define initial state for the in-memory bucket storage.
bucket
object
Map of bucket keys to initial values.
bucket:
  user_count: 0
  last_login: null
Access bucket values in templates: {{bucket "user_count"}}

Endpoints

Define the API endpoints your service exposes.
endpoints
array
required
Array of endpoint definitions.
endpoints[].kind
string
Type of endpoint.Options:
  • http - Standard HTTP request/response (default)
  • websocket or ws - WebSocket endpoint
  • sse - Server-Sent Events endpoint
Default: http
endpoints[].method
string
required
HTTP method for the endpoint.Options: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
endpoints[].path
string
required
URL path for the endpoint. Must start with /.Supports path parameters using curly braces: /users/{id}
endpoints[].description
string
Human-readable description of what this endpoint does.
endpoints[].header_match
object
Optional headers that must match for this endpoint to trigger. Useful for API versioning.
header_match:
  X-API-Version: "2.0"
endpoints[].parameters
array
Array of parameter definitions.
endpoints[].parameters[].name
string
required
Parameter name.
endpoints[].parameters[].in
string
required
Parameter location: path, query, or header.
endpoints[].parameters[].type
string
required
Parameter data type: string, number, integer, boolean.
endpoints[].parameters[].required
boolean
required
Whether the parameter is required.
endpoints[].parameters[].description
string
Parameter description.
endpoints[].request_body
object
Expected request body definition.
endpoints[].request_body.required
boolean
Whether a request body is required.Default: false
endpoints[].request_body.schema
string
Reference to a model name defined in the models section.
endpoints[].request_body.content_type
string
Expected content type for the request body.Example: application/json
endpoints[].responses
object
required
Map of HTTP status codes to response definitions. Must have at least one response.
endpoints[].responses[status].content_type
string
required
Response content type.Example: application/json, text/plain
endpoints[].responses[status].body
string
required
Response body as a string. Supports Handlebars templates for dynamic content.Template variables:
  • {{request.body}} - Request body
  • {{request.query.param}} - Query parameters
  • {{request.params.id}} - Path parameters
  • {{now}} - Current timestamp
  • {{uuid}} - Random UUID
  • {{faker "name.firstName"}} - Faker.js data
endpoints[].responses[status].condition
string
Handlebars condition that must evaluate to true for this response to be used.
condition: "{{eq request.query.type 'premium'}}"
endpoints[].responses[status].schema
string
Reference to a model name for response validation.
endpoints[].responses[status].script
string
Path to a JavaScript/TypeScript file that generates the response programmatically.
endpoints[].responses[status].headers
object
Additional response headers.
headers:
  X-Rate-Limit: "100"
  Cache-Control: "no-cache"
endpoints[].responses[status].side_effects
array
Side effects to trigger when this response is sent.
endpoints[].responses[status].side_effects[].action
string
required
Action to perform: set, increment, decrement.
endpoints[].responses[status].side_effects[].target
string
required
Target bucket key to modify.
endpoints[].responses[status].side_effects[].value
string
required
Value to set (supports templates).
endpoints[].scenarios
array
Scenario-based responses with conditional matching.
endpoints[].scenarios[].name
string
Scenario name for manual selection.
endpoints[].scenarios[].conditions
object
Conditions for this scenario to match.
endpoints[].scenarios[].conditions.query
object
Query parameters that must match.
endpoints[].scenarios[].conditions.headers
object
Headers that must match.
endpoints[].scenarios[].conditions.body
object
Body fields that must match.
endpoints[].scenarios[].response
object
required
Response to return when this scenario matches.
endpoints[].scenarios[].response.status
number
required
HTTP status code.
All fields from the standard response definition are supported.
endpoints[].scenarios[].strategy
string
Strategy for auto-selecting scenarios: sequential or random.
endpoints[].stream
object
Streaming configuration for WebSocket and SSE endpoints.
endpoints[].stream.initial
array
Messages sent immediately after connection.
stream:
  initial:
    - '{"type": "welcome", "message": "Connected"}'
endpoints[].stream.periodic
object
Periodic message configuration.
endpoints[].stream.periodic.interval_ms
number
required
Interval in milliseconds between messages.
endpoints[].stream.periodic.message
string
required
Message template (supports Handlebars).

GraphQL configuration

Configure GraphQL endpoint support.
graphql
object
GraphQL configuration for the service.
graphql.schema_path
string
required
Path to the GraphQL schema file (.graphql).
graphql.mocks
object
required
Map of operation names to Handlebars template files.
graphql:
  schema_path: schema.graphql
  mocks:
    getUser: templates/get-user.hbs
    listUsers: templates/list-users.hbs

Behavior simulation

Configure behavior simulation for this specific service.
behavior
object
Behavior configuration that overrides global settings.
behavior.latency
object
Simulate network latency.
behavior.latency.min_ms
number
required
Minimum latency in milliseconds.
behavior.latency.max_ms
number
required
Maximum latency in milliseconds.
behavior.error_simulation
object
Simulate random errors.
behavior.error_simulation.enabled
boolean
required
Enable error simulation.
behavior.error_simulation.rate
number
required
Error rate between 0.0 and 1.0.
behavior.error_simulation.status_codes
array
HTTP status codes to return when simulating errors.
behavior.rate_limiting
object
Simulate rate limiting.
behavior.rate_limiting.enabled
boolean
required
Enable rate limiting.
behavior.rate_limiting.requests_per_minute
number
required
Maximum requests allowed per minute.

Complete example

name: User Service
version: "2.0"
description: Complete user management API

server:
  port: 9010
  base_path: /api/v2
  cors:
    enabled: true
    origins:
      - http://localhost:3000
    methods:
      - GET
      - POST
      - PUT
      - DELETE

models:
  User:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      email:
        type: string
    required:
      - name
      - email

fixtures:
  default_users:
    - id: 1
      name: Alice
      email: [email protected]
    - id: 2
      name: Bob
      email: [email protected]

bucket:
  user_count: 2

endpoints:
  - method: GET
    path: /users
    description: List all users
    responses:
      200:
        content_type: application/json
        body: |
          {{json (fixture "default_users")}}

  - method: POST
    path: /users
    description: Create a new user
    request_body:
      required: true
      schema: User
      content_type: application/json
    responses:
      201:
        content_type: application/json
        body: |
          {
            "id": {{bucket "user_count"}},
            "name": "{{request.body.name}}",
            "email": "{{request.body.email}}",
            "created_at": "{{now}}"
          }
        side_effects:
          - action: increment
            target: user_count
            value: "1"

  - method: GET
    path: /users/{id}
    description: Get a specific user
    parameters:
      - name: id
        in: path
        type: integer
        required: true
        description: User ID
    responses:
      200:
        content_type: application/json
        body: |
          {
            "id": {{request.params.id}},
            "name": "User {{request.params.id}}",
            "email": "user{{request.params.id}}@example.com"
          }

behavior:
  latency:
    min_ms: 50
    max_ms: 200
  error_simulation:
    enabled: false
    rate: 0.0

Validation

Apicentric validates your service definitions when loading them:
  • HTTP methods must be valid (GET, POST, etc.)
  • Paths must start with /
  • Each endpoint must have at least one response
  • Status codes must be between 100-599
  • Content types must be non-empty
You’ll see detailed validation errors if any issues are found.

Best practices

  1. Use models for consistency - Define reusable JSON schemas for common data structures
  2. Leverage fixtures for test data - Keep test data organized and reusable
  3. Use templates for dynamic responses - Make responses realistic with Handlebars helpers
  4. Add descriptions - Document your endpoints to help team members understand the API
  5. Test with behaviors - Use latency and error simulation to test your application’s resilience

Build docs developers (and LLMs) love