Amock is a simple API mock server that uses JSON files to define entities from which it auto-generates endpoints. It is useful for front-end developers who need to work with a back-end API that is not yet available.
- Amock
npm install -g amock-clibrew install matronator/tap/amockGo to the releases page and download the latest version for your OS. Extract the files and do either one of these:
- Move the binary to a folder in your
$PATH, or... - Add the folder to your
$PATH
sudo mv path/to/extracted/binary/amock /usr/local/binmove path\to\extracted\binary\amock.exe C:\path\to\binFirst move the extracted binary to some permanent folder. Then add the directory to your PATH by running:
export PATH=$PATH:path/to/extracted/binaryTo make this permanent, add this line to your ~/.bashrc or ~/.zshrc or ~/.profile file.
- Open
"My Computer" > "Properties" > "Advanced" > "Environment Variables" > "Path" - Add the path to the
amock.exefile to the list - Restart your terminal
$PATH = [Environment]::GetEnvironmentVariable("PATH", "Machine")
$amock_path = "C:\path\to\amock"
if( $PATH -notlike "*"+$amock_path+"*" ){
[Environment]::SetEnvironmentVariable("PATH", "$PATH;$amock_path", "Machine")
}Important
Requires Go 1.16 or later
git clone https://github.com/matronator/amock.git
cd amock
go build -o cmd/amock -ldflags="-s -w" .
sudo mv cmd/amock /usr/local/bin
# have to use sudo because /usr/local/bin is protectedMake sure that /user/local/bin is in your PATH. If not edit your ~/.bashrc or ~/.zshrc or ~/.profile and add the following line:
export PATH=$PATH:/usr/local/bingit clone https://github.com/matronator/amock.git
cd amock
go build -o cmd/amock.exe -ldflags="-s -w" .Next move the amock.exe to some permanent location and add it to your PATH with either the GUI or PowerShell:
- Open
"My Computer" > "Properties" > "Advanced" > "Environment Variables" > "Path" - Add the path to the
amock.exefile to the list - Restart your terminal
$PATH = [Environment]::GetEnvironmentVariable("PATH", "Machine")
$amock_path = "C:\path\to\amock"
if( $PATH -notlike "*"+$amock_path+"*" ){
[Environment]::SetEnvironmentVariable("PATH", "$PATH;$amock_path", "Machine")
}After installing you can simply start the server by running:
amockYou can also optionally specify the host you want to use for the server by supplying it as the first argument like this:
amock localhost:1234This will overwrite the host and port set in your config file and start the server on localhost:1234.
You need to create a config file for the server to be of any use. The config file is a JSON/YAML/TOML file that defines the entities that the server will mock and some other settings. Valid config file names are these in order of priority (the first one found will be used):
[".amock.json", ".amockrc.json", ".amock.json.json", ".amock.json.yml",
".amock.json.yaml", ".amock.json.toml", "amock.config",
"amock.json", "amock.yml", "amock.yaml", "amock.toml"]Here is an example of a config file:
// .amock.json
{
"host": "localhost", // default is localhost
"port": 8080, // default is 8080
"entities": [ // default is empty
"user.json", // relative path to the entity file
"post.json"
],
"dir": "relative/path/to/entities/dir", // default is empty
"initCount": 20 // default is 20 - number of entities to generate on server start
}Alternatively you can define environment variables or an .env file to configure the server. The environment variables (with defaults) are:
AMOCK_HOST=localhost
AMOCK_PORT=8080
AMOCK_DIR='path/to/entities' # default is empty
AMOCK_ENTITIES='[user.json, post.json]' # default is empty
AMOCK_INIT_COUNT=20You must set either entities where you list individual files or dir where you specify a directory containing the entity files and all valid files in that directory will be used.
You can set both but files from entities will override files with the same name found in the dir directory. Both entities and dir are optional but at least one must be set and paths in both are relative to the config file.
Entity files are JSON files that define the structure of the entities that the server will mock. The name of the file will be the name of the entity and the name of the endpoints.
Here is an example of an entity file:
// user.json
{
"id": "id.sequence",
"name!": "string.firstname",
"surname!": "string.lastname",
"age": "number.int:18-64",
"birthday": "date:yyyy-MM-dd",
"money": "number.decimal:2,0-10000",
"email": "string.email",
"password": "string.password",
"username": "string.username",
"city?": "string.city",
"street?": "string.street",
"country?": "string.country:short",
"role": "enum:admin,user,moderator",
"is_active": "bool",
"token": "string",
"created_at": "date.timestamp",
"updated_at": "date.timestamp"
}This would generate an entity object user looking like this:
{
"id": 1,
"name": "Hal",
"surname": "Kling",
"age": 27,
"birthday": "1996-10-29",
"money": 7170.82,
"email": "lucianonienow@schinner.org",
"password": "jcFWmf$y4gOp@&6o",
"username": "Toy3451",
"city": "Chesapeake",
"street": "981 South Keyston",
"country": "AL",
"role": "user",
"is_active": true,
"token": "p?sb",
"created_at": 1168432992,
"updated_at": 701208326
}When defining your entity you can use the following types and the server will generate the data for you. Data is generated once on server start if not already in store and whenever a new entity is created without specifying the property (if it's not required).
The syntax for defining a property is
"<name>": "<type>.<subtype?>:<options>"
where name is the name of the property, type is the type of the property followed by a dot and an optional subtype and optionally a colon followed by options for the type.
If the property name ends with ! it is required and must be present in the request. If it ends with ? it is nullable meaning that you can send a null value for it in your request.
Tip
You can check some examples of how to define entities in the examples folder.
You can use the following types and subtypes to define your properties:
"string": {
"": Random string, // no subtype
"name": Full name,
"firstname": First name,
"lastname": Last name,
"email": Email address,
"url": Url,
"ip": Ip,
"ipv6": Ipv6,
"username": Username,
"password": Password,
"phone": Phone number,
"zip": Zip,
"country": Country, // with following options
["short": Short country code],
"city": City,
"street": Street,
"streetName": Street name,
"state": State, // with following options
["short": Short country code],
"company": Company name,
"bitcoin": Bitcoin address,
"color": Color, // width following options
["": Color name in English], // default
["hex": Color in hex format],
["safe": Web safe color],
["rgb": Color in RGB format],
"word": Random word,
"sentence": Random sentence,
[int: Number of words in sentence], // default 3
"paragraph": Random paragraph,
[int: Number of paragraphs], // default 3
},
"number": {
"": Random number, // no subtype
"int": Random integer,
"decimal": Random decimal number,
"float": Random float,
"range": Random float in Range,
},
"date": {
"": Date, // no subtype, but you can specify the format
[string: Date format (e.g. yyyy-MM-dd)],
"timestamp": Timestamp,
"day": Day,
"month": Month,
"year": Year,
"weekday": WeekDay,
"future": Future,
"past": Past,
},
"bool": true or false,
"enum": Pick a random item from the list provided in options, separated by commas,
"id": {
"": Sequential ID, // no subtype
"sequence": Sequential ID,
"uuid": UUID,
},After you have your config file and entity files set up you can start the server by running:
amockWhich, if we used the user entity from above, would generate the following endpoints:
GET /users- returns an array of usersGET /users/:id- returns a single userPOST /users- creates a new user or updates existing one if the ID matches one already in the database. You can post a single user or a collection as an arrayPUT /users- same as POST for now- More endpoints will be added in the future...
You can access the server at http://localhost:8080 or whatever host and port you set in your config file. You can access the endpoints with a REST client like Postman or Insomnia or even in a browser.
Whatever operations you do on the entities will be saved in a file and will be available even after you restart the server.
This project was inspired by json-server and uses the gofakeit library for generating data.
Check the LICENSE file for more information.
Matronator © 2024
