Table of Contents
JumbleAPI is a zero-config mock server designed to test how your frontend handles unpredictable real-world API behaviors. Beyond generating schema-driven JSON responses, JumbleAPI lets you inject deliberate chaos into your data layer—allowing you to easily test UI state resilience against response latency, unexpected status codes, missing properties, invalid data types, and corrupted keys.
- Generate random mock output from JSON schema definitions
- Support for random value types, arrays,
pickFromlists, and faker-powered mock formats - Optional response mutation: missing fields, wrong types, malformed keys
- Dedicated endpoints for custom HTTP status and artificial delay
- Schema management API for create/read/update/delete operations
npm install --save-dev jumble-apinpm install -g jumble-apinpx jumble-api --port 3030 --schema src/schemas.jsThis will run locally hosted API on http://localhost:3030.
This will also load the user defined schemas on the directory specified (.js format).
Refer to Schema Format and Schema File Declaration section down below to learn how to define custom schemas.
// package.json
{
"name": "my-project",
"scripts": {
"mock:api": "jumble-api --port 3030"
}
}Then start your server anytime by running:
npm run mock:apicurl http://localhost:3030/api/jumble// Default Schema
{
"success": true,
"data": {
"id": "71a54855-9335-4902-bea7-20658f4a5440",
"firstname": "Edgar",
"lastname": "Keebler",
"sex": "male",
"email": "Angelo_Cruickshank77@gmail.com",
"phone": "09232135085",
"profilePic": "https://avatars.githubusercontent.com/u/1747281"
}
}jumble-api --port 3030 --schema ./schemas.js{
"success": true,
"data": { ... }
}- success: Indicates the success of the response process.
- data: Contains the data generated from the schema.
{
"success": false,
"msg": "Error Message"
}- success: Indicates the success of the response process.
- msg: Contains the error message returned by the process.
--port,-p— port number (default:3030)--schema,-s— schema directory or schema file path loaded at startup
Schemas support either a simple type string or an object with optional properties:
format— indicate format of data, you may select from the following:- primary types:
string,number,boolean, anddate; or - mock types:
fullname,firstname,lastname,sex,email,phone,url,imageUrl,avatarUrl,portrait,countryCode,address,color,zipcode,currency, anduuid.
- primary types:
pickFrom— select values from a provided list.array— a number or{ min, max }length definition.min/max— optional numeric bounds for generated values.properties— defines properties of object (can be used define nested objects).
Type of an element can be declared as a string passed onto a key or inside an object with the format key. The object type declaration allows for further customization of options.
{
"name": "fullname", // Simple Type String
"email": {
"format": "email" // Option Type Declaration
}
}Objects can be declared in a schema by passing an object with the properties key inside it.
The properties key is a reserved keyword for declaring an object.
{
"name": "fullname",
"gender": "sex",
"nestedObject": {
"properties": {
// Declares Nested Object
"nestedString": "string",
"nestedNumber": "number"
}
}
}As such, the whole schema can also be wrapped in the properties tag. (This allows customization of options to the schema itself).
{
"properties": {
"name": "fullname",
"age": "number",
"email": {
"format": "email"
}
}
}Arrays can be declared in the schema by passing an array key like so.
{
"name": "fullname",
"age": "number",
"friends": {
"array": 6, // Returns array of fullnames with length of 6
"format": "fullname"
},
"posts": {
"array": { "min": 5, "max": 10 }, // Returns array of objects with min length 5 and max length 10
"properties": {
"title": "string",
"description": "string",
"likes": "number"
}
}
}If you want the response itself to be an array, it can be declared like so.
{
"array": 10, // Returns an array of 10
"properties": {
"name": "fullname",
"age": "number",
"posts": {
"array": { "min": 5, "max": 10 },
"properties": {
"title": "string",
"description": "string",
"likes": "number"
}
}
}
}The min and max properties in format type declarations function depending on what format it was used on. The formats it is used on are number, string, and date.
{
"sentence": {
"format": "string", // For strings, these define the number of words to return
"min": 10,
"max": 20
},
"age": {
"format": "number", // For numbers, these define the minimum and maximum value
"min": 18,
"max": 99
},
"createdAt": {
"format": "date", // For dates, these define the minimum and maximum date range
"min": "2026-09-11T12:00:00Z", // These accept either a valid ISO 8601 string or a UNIX Timestamp in Milliseconds
"max": 1789128000000
}
}The pickFrom property in format type declaration is passed in an array and it defines the list of values to choose from and return. Users must use this if the values cannot be represented by existing format types.
{
"name": "fullname",
"email": "email",
"userType": {
"pickFrom": ["admin", "user"] // Randomly chooses and returns from the list
}
}If both format and pickFrom property is defined in the type, the pickFrom property will be prioritized.
In the --schema param, the directory of your schema file is read by the application and registers it as available schema.
To declare a schemas file, create a JavaScript file and export default an object where each key is a schemaID (used to reference the schema in endpoints) and each value is the schema definition.
export default {
schemaID: {
key: format,
},
};export default {
schema1: {
name: "fullname",
sex: "sex",
email: "email",
},
schema2: {
name: "fullname",
sex: "sex",
email: "email",
},
};After creating the file, pass its path to the --schema option when starting the API:
npx jumble-api --schema src/schemas.jsTo reference declared schemas, pass the schema ID as a query parameter in the endpoint url like this.
http://localhost:3030/api/jumble?schemaID=schema1
All endpoints are mounted under /api.
Generate schema-based JSON output.
Query parameters:
schemaID— optional schema identifier to usemissing=1— remove some keyswrongType=1— use wrong types for some valuesmalformed=1— corrupt some property namesprobability=<number>— probability of applying mutation logic (default: 1)
Generates output with random mutation flags and random probability.
http://localhost:3030/api/jumble?missing=1&wrongType=1&malformed=1&probability=0.5&schemaID=schema1
// Schema Input
{
"name": "fullname",
"age": {
"format": "number",
"min": 18,
"max": 100,
},
"sex": "sex"
}
// Output (Missing "age" element)
{
"success": true,
"data": {
"namd": "John Doe", // Malformed Element Key
"sex": true // Wrong Data Type
}
}Return schema output with custom or random HTTP status.
Returns a random HTTP status code and schema output.
Returns schema output with the requested status code.
http://localhost:3030/api/status/404
// Schema Input (schemaID=schema1)
{
"name": "fullname",
"age": {
"format": "number",
"min": 18,
"max": 100,
},
"sex": "sex"
}
// Output (STATUS CODE = 404 NOT FOUND)
{
"success": true,
"data": {
"name": "John Doe",
"age": 56,
"sex": "male"
}
}Not to be confused with an actual 404 NOT FOUND response, in this case the success key will be false.
// Output (STATUS CODE = 404 NOT FOUND)
{
"success": false,
"msg": "Schema with ID 'schema1' does not exist."
}Simulate response latency.
Query parameters:
schemaID— optional schema identifiervalue— delay amount (default:5000)units— one ofms,us,ns,s(default:ms)
Returns schema output. The response will be delayed by a random amount between 0 to 30 seconds.
http://localhost:3030/api/delay?value=5&units=s&schemaID=schema1
// Schema Input (schemaID=schema1)
{
"name": "fullname",
"age": {
"format": "number",
"min": 18,
"max": 100,
},
"sex": "sex"
}
// Output (Arrives after 5 seconds)
{
"success": true,
"data": {
"name": "John Doe",
"age": 56,
"sex": "male"
}
}Manage available schema definitions.
Returns all currently loaded schemas.
Returns a specific schema by ID.
Creates a new schema. Request body should be:
{
"schemaID": "mySchema",
"schema": { ... }
}Updates an existing schema with the same request payload.
Deletes the schema with the given ID.
http://localhost:3030/api/schema/schema1
-
While an endpoint for
schemasexists, the changes made with this endpoint do not persist between runtimes (stopping the server and running it again). The most reliable way to define schemas is still defining it onschemas.jsfile and passing the path to the--schemaoption. -
For flexibility purposes purposes, each route for the
delay,status, andjumbleendpoint has aPOSTmethod equivalent with exact same functionality. Instead of referencing the schema through theschemaIDquery parameter, you may send the schema in the request body. -
If
schemaIDis not provided, the API uses the default schema.Default Schema:
{ id: "uuid", firstname: "firstname", lastname: "lastname", sex: "sex", email: "email", phone: "phone", profilePic: "avatarUrl", }
-
Invalid query parameters or schema payloads return appropriate 4xx error responses.
Distributed under the ISC License. See LICENSE for more information.
Masato Mizunuma - GitHub - LinkedIn - masatomizunuma911@gmail.com
Project Link: https://github.com/Mizuto911/jumble-api