API Reference

Basic Specifications

mocks automatically generates RESTful API endpoints based on the structure of JSON files. All endpoints send and receive data with Content-Type: application/json.

Endpoint Types

Array Resources

For resources defined as arrays (e.g., posts, comments), the following endpoints are generated:

Method	Path	Description
GET	/{resource}	Get all items
GET	/{resource}?{query}	Get items based on search criteria
GET	/{resource}/{id}	Get specific item
POST	/{resource}	Create new item
PUT	/{resource}/{id}	Replace existing item completely
PATCH	/{resource}/{id}	Update existing item partially
DELETE	/{resource}/{id}	Delete existing item

Single Object Resources

For resources defined as objects (e.g., profile), the following endpoints are generated:

Method	Path	Description
GET	/{resource}	Get object
PUT	/{resource}	Replace object completely
PATCH	/{resource}	Update object partially

Search Functionality

For array-type resources, you can use query parameters for searching.

Search Parameter Format

{field}.{matchtype}={value}

Supported Match Types

Match Type	Description	Example
exact	Exact match (case-insensitive)	title.exact=Hello
contains	Partial match (case-insensitive)	title.contains=world
startswith	Prefix match (case-insensitive)	title.startswith=Hello
endswith	Suffix match (case-insensitive)	title.endswith=World

Search Limitations

• Search is only available for array resource listing (GET /{resource})
• Cannot be used for single item retrieval (GET /{resource}/{id})
• Complex values (objects or arrays) cannot be searched
• Match type is required (formats like field=value are not allowed)

Multiple Condition Search

When combining multiple search conditions, they are joined with AND logic:

curl "http://localhost:3000/posts?title.contains=post&views.exact=100"

HTTP Status Codes

Status Code	Description
200 OK	Request completed successfully
201 Created	New resource created
204 No Content	Request completed successfully (no response body)
400 Bad Request	Invalid request
404 Not Found	Specified resource not found
405 Method Not Allowed	Unsupported HTTP method
500 Internal Server Error	Server internal error

Special Endpoints

Health Check

GET /_hc

Endpoint for checking server status. Always returns 204 No Content.

CLI Options

Options available when starting the mocks server:

Option	Short	Default	Description
--host	-H	localhost	Host address to bind to
--port	-p	3000	Port number to bind to
--no-overwrite	none	false	Prevent overwriting original JSON file
--help	-h	none	Display help message
--version	-V	none	Display version information

Limitations

• Resource names must be unique (cannot coexist api/v1/users and api/v2/users)
• Each item in array resources needs a unique ID
• JSON file changes are automatically saved to the original file (can be disabled with --no-overwrite option)

Debug Features

By setting the MOCKS_DEBUG_OVERWRITTEN_FILE environment variable, you can save modified data to a separate file:

MOCKS_DEBUG_OVERWRITTEN_FILE=storage.debug.json mocks run storage.json

This feature is useful for debugging during development.