Location
By default, service definition files are stored in the directory specified bysimulator.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.yamlpayment-api.yamlinventory.yml
Basic structure
Service metadata
Define basic information about your service.The name of your service. This appears in logs and the admin interface.
Semantic version of your service definition.Example:
"1.0", "2.1.0"Human-readable description of what this service does.
Server configuration
Configure how your service listens for requests.Server configuration for the service
Port number to listen on. If not specified, Apicentric automatically assigns a port from the configured range.
Base path prefix for all endpoints. Must start with
/.Example: /api/v1, /, /servicesBase URL to proxy requests when no local endpoint matches. Useful for partial mocking.Example:
http://production-api.example.comWhen enabled with
proxy_base_url, automatically records proxied responses for later use.Default: falseCORS configuration for cross-origin requests.
Enable CORS support.
List of allowed origins.Example:
["http://localhost:3000", "https://app.example.com"]Allowed HTTP methods.Example:
["GET", "POST", "PUT", "DELETE"]Allowed request headers.Example:
["Content-Type", "Authorization"]Data models
Define reusable JSON schemas for request and response validation.Map of model names to JSON Schema definitions.
Fixtures
Define reusable test data that can be referenced in responses.Map of fixture names to data objects.You can reference fixtures in responses using Handlebars:
{{fixture "users"}}Bucket storage
Define initial state for the in-memory bucket storage.Map of bucket keys to initial values.Access bucket values in templates:
{{bucket "user_count"}}Endpoints
Define the API endpoints your service exposes.Array of endpoint definitions.
Type of endpoint.Options:
http- Standard HTTP request/response (default)websocketorws- WebSocket endpointsse- Server-Sent Events endpoint
httpHTTP method for the endpoint.Options:
GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONSURL path for the endpoint. Must start with
/.Supports path parameters using curly braces: /users/{id}Human-readable description of what this endpoint does.
Optional headers that must match for this endpoint to trigger. Useful for API versioning.
Array of parameter definitions.
Parameter name.
Parameter location:
path, query, or header.Parameter data type:
string, number, integer, boolean.Whether the parameter is required.
Parameter description.
Expected request body definition.
Whether a request body is required.Default:
falseReference to a model name defined in the
models section.Expected content type for the request body.Example:
application/jsonMap of HTTP status codes to response definitions. Must have at least one response.
Response content type.Example:
application/json, text/plainResponse 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
Handlebars condition that must evaluate to true for this response to be used.
Reference to a model name for response validation.
Path to a JavaScript/TypeScript file that generates the response programmatically.
Additional response headers.
Side effects to trigger when this response is sent.
Action to perform:
set, increment, decrement.Target bucket key to modify.
Value to set (supports templates).
Scenario-based responses with conditional matching.
Scenario name for manual selection.
Response to return when this scenario matches.All fields from the standard response definition are supported.
HTTP status code.
Strategy for auto-selecting scenarios:
sequential or random.Streaming configuration for WebSocket and SSE endpoints.
Messages sent immediately after connection.
GraphQL configuration
Configure GraphQL endpoint support.Behavior simulation
Configure behavior simulation for this specific service.Behavior configuration that overrides global settings.
Complete example
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
Best practices
- Use models for consistency - Define reusable JSON schemas for common data structures
- Leverage fixtures for test data - Keep test data organized and reusable
- Use templates for dynamic responses - Make responses realistic with Handlebars helpers
- Add descriptions - Document your endpoints to help team members understand the API
- Test with behaviors - Use latency and error simulation to test your application’s resilience
Related pages
- apicentric.json - Main configuration file
- Environment Variables - Environment variable reference