Skip to content


Repository files navigation

Cruddie Mock

Dead simple API mocking tool. Supply a folder full of json files describing your models, get a working REST API with CRUD methods for mock data. Cruddie Mock was built with simplicity in mind, so it should set you up for success.

For an example server, you can run the tool against the json files in the examples/application folder. You can download the zip file from github, then extract it somewhere. Then, open a command line window to the unzipped directory, and run:

cruddie-mock ./examples/application

The json supporting this is in the application example folder.

Quickstart Guide

  1. Install cruddie-mock globally: npm install -g cruddie-mock
  2. Create your models using json objects in your project. (See examples folder)
  3. From the command line, open the folder your json files are in
  4. Start the server: cruddie-mock
  5. Open http://localhost:3009/

Command Line Usage

Usage: cruddie-mock [options] [directory path]

[directory path] should be a directory with json files describing your models. If
omitted, the current working directory will be used instead. Regular require-style
javascript (.js) files will also work - export your model.


cruddie-mock provides a number of command-line options to make configuring it simple for most use cases. All options are also available as environment variables. If both are provided, command line options override environment variables.

Argument Short Arg Environment Var Description
--port -p PORT Port to run process on (default 3009)
--result-count -r RESULT_COUNT Number of results to put in an API by default. (default 50)
--host n/a HOST Host to bind to. (Default, or all interfaces)
--no-cors n/a NO_CORS Disable Cross-Origin Resource Sharing
--no-gzip n/a NO_GZIP Disable ZIP compression in responses
--swagger-url n/a SWAGGER_URL Domain/port used for API. Use if hosting on a domain instead of localhost.
--read-only n/a READ_ONLY Only allow GET requests
--version v n/a Print version and exit

Model Format

Models are simply json files with a special syntax for anything you want to be randomized. A plain json file will also work. For some live examples, check the examples folder.

Built-in variables

Key Example Description
{{id}} 1 Auto-incrementing ID. Unique per model
{{example}} example The word example. Used for documentation.
{{foreign_id(model_name}} 5 A valid id that links to the model named in parenthesis

Faker-powered Variables


Key Example Description
{{address.zipCode}} 86966 zipCode object.
{{}} Gradybury city object.
{{address.cityPrefix}} Lake cityPrefix object.
{{address.citySuffix}} borough citySuffix object.
{{address.streetName}} Bridget Village streetName object.
{{address.streetAddress}} 411 Dare Canyon streetAddress object.
{{address.streetSuffix}} Key streetSuffix object.
{{address.streetPrefix}} c streetPrefix object.
{{address.secondaryAddress}} Suite 116 secondaryAddress object.
{{address.county}} Avon county object.
{{}} Tokelau country object.
{{address.countryCode}} CI countryCode object.
{{address.state}} Alabama state object.
{{address.stateAbbr}} MS stateAbbr object.
{{address.latitude}} -51.6628 latitude object.
{{address.longitude}} 126.4665 longitude object.


Key Example Description
{{commerce.color}} orange color object.
{{commerce.department}} Electronics department object.
{{commerce.productName}} Fantastic Granite Gloves productName object.
{{commerce.price}} 151.00 price object.
{{commerce.productAdjective}} Sleek productAdjective object.
{{commerce.productMaterial}} Fresh productMaterial object.
{{commerce.product}} Ball product object.


Key Example Description
{{company.suffixes}} Inc,and Sons,LLC,Group suffixes object.
{{company.companyName}} Rosenbaum Inc companyName object.
{{company.companySuffix}} Group companySuffix object.
{{company.catchPhrase}} Optional cohesive approach catchPhrase object.
{{}} next-generation whiteboard vortals bs object.
{{company.catchPhraseAdjective}} Polarised catchPhraseAdjective object.
{{company.catchPhraseDescriptor}} context-sensitive catchPhraseDescriptor object.
{{company.catchPhraseNoun}} forecast catchPhraseNoun object.
{{company.bsAdjective}} end-to-end bsAdjective object.
{{company.bsBuzz}} incubate bsBuzz object.
{{company.bsNoun}} e-commerce bsNoun object.


Key Example Description
{{database.column}} name column object.
{{database.type}} decimal type object.
{{database.collation}} cp1250_bin collation object.
{{database.engine}} MEMORY engine object.


Key Example Description
{{date.past}} Fri Aug 04 2017 12:01:40 GMT-0400 (Eastern Daylight Time) past object.
{{date.future}} Mon Jan 01 2018 19:15:34 GMT-0500 (Eastern Standard Time) future object.
{{date.recent}} Fri Sep 08 2017 18:23:21 GMT-0400 (Eastern Daylight Time) recent object.
{{date.month}} March month object.
{{date.weekday}} Sunday weekday object.


Key Example Description
{{finance.account}} 81777179 account object.
{{finance.accountName}} Credit Card Account accountName object.
{{finance.mask}} 0926 mask object.
{{finance.amount}} 275.73 amount object.
{{finance.transactionType}} deposit transactionType object.
{{finance.currencyCode}} VEF currencyCode object.
{{finance.currencyName}} Zimbabwe Dollar currencyName object.
{{finance.currencySymbol}} £ currencySymbol object.
{{finance.bitcoinAddress}} 1632O02TB7R9R2CXJQMWVMBL23K4 bitcoinAddress object.
{{finance.iban}} LV51LLBW360H89FZ74H3I iban object.
{{finance.bic}} FFVEHRE1 bic object.


Key Example Description
{{hacker.abbreviation}} SAS abbreviation object.
{{hacker.adjective}} 1080p adjective object.
{{hacker.noun}} bandwidth noun object.
{{hacker.verb}} back up verb object.
{{hacker.ingverb}} hacking ingverb object.
{{hacker.phrase}} You can't copy the microchip without navigating the open-source GB program! phrase object.


Key Example Description
{{image.image}} image object.
{{image.avatar}} avatar object.
{{image.imageUrl}} imageUrl object.
{{image.abstract}} abstract object.
{{image.animals}} animals object.
{{}} business object.
{{image.cats}} cats object.
{{}} city object.
{{}} food object.
{{image.nightlife}} nightlife object.
{{}} fashion object.
{{image.people}} people object.
{{image.nature}} nature object.
{{image.sports}} sports object.
{{image.technics}} technics object.
{{image.transport}} transport object.
{{image.dataUri}} [Data URI goes here] A Data URI object.


Key Example Description
{{internet.avatar}} avatar object.
{{}} email object.
{{internet.exampleEmail}} exampleEmail object.
{{internet.userName}} Marge_Hettinger userName object.
{{internet.protocol}} https protocol object.
{{internet.url}} url object.
{{internet.domainName}} domainName object.
{{internet.domainSuffix}} biz domainSuffix object.
{{internet.domainWord}} lacy domainWord object.
{{internet.ip}} ip object.
{{internet.ipv6}} c58a:23c6:39f8:ad74:2e72:28ac:8f96:3b3f ipv6 object.
{{internet.userAgent}} Mozilla/5.0 (compatible; MSIE 8.0; Windows NT 6.1; Trident/7.0; .NET CLR 2.0.57178.2) userAgent object.
{{internet.color}} #5b2c38 color object.
{{internet.mac}} 48:4e:65:ff:a6:7b mac object.
{{internet.password}} aqb0BbU44XSkgbV password object.


Key Example Description
{{lorem.word}} qui word object.
{{lorem.words}} accusantium earum qui words object.
{{lorem.sentence}} Quo quas omnis assumenda libero. sentence object.
{{lorem.slug}} saepe-est-sunt slug object.
{{lorem.sentences}} Lorem ipsum... A few sentences.
{{lorem.paragraph}} Lorem ipsum... A paragraph.
{{lorem.paragraphs}} Lorem ipsum... A few paragraphs.
{{lorem.text}} Lorem ipsum... Lorem ipsum text with newline characters.
{{lorem.lines}} Lorem ipsum... Lorem ipsum text with newline characters.


Key Example Description
{{name.firstName}} Fletcher firstName object.
{{name.lastName}} Blick lastName object.
{{name.findName}} Hiram Hoeger findName object.
{{name.jobTitle}} Dynamic Accountability Assistant jobTitle object.
{{name.prefix}} Dr. prefix object.
{{name.suffix}} Sr. suffix object.
{{name.title}} Senior Metrics Planner title object.
{{name.jobDescriptor}} Dynamic jobDescriptor object.
{{name.jobArea}} Web jobArea object.
{{name.jobType}} Technician jobType object.


Key Example Description
{{phone.phoneNumber}} 681.712.3445 x781 phoneNumber object.
{{phone.phoneNumberFormat}} 273-435-5932 phoneNumberFormat object.
{{phone.phoneFormats}} (###) ###-#### x### phoneFormats object.


Key Example Description
{{random.number}} 30148 number object.
{{random.arrayElement}} c arrayElement object.
{{random.objectElement}} bar objectElement object.
{{random.uuid}} b0223f3a-48af-4aaa-aecc-eda906c19304 uuid object.
{{random.boolean}} false boolean object.
{{random.word}} Credit Card Account word object.
{{random.words}} Avon olive Fish words object.
{{random.image}} image object.
{{random.locale}} ko locale object.
{{random.alphaNumeric}} n alphaNumeric object.


Key Example Description
{{system.fileName}} next_generation_best_of_breed.atc fileName object.
{{system.commonFileName}} tangible_central_tools.mpga commonFileName object.
{{system.mimeType}} application/cals-1840 mimeType object.
{{system.commonFileType}} video commonFileType object.
{{system.commonFileExt}} wav commonFileExt object.
{{system.fileType}} image fileType object.
{{system.fileExt}} csml fileExt object.
{{system.semver}} 9.5.3 semver object.

Linking models together

If you define multiple models, the foreign_id field will let you link them together, similar to a join in mysql. cruddie-mock will look at the other model you reference, and pick a random id to link it to. Here's what it looks like, with an excerpt from upload.json in the application example:

  "name": "{{system.fileName}}",
  "userId": "{{foreign_id(user)}}"

As long as you have a user model, this will find a valid user id to put into this field. This by itself is kinda useful, but you can also use the API to fetch all uploads owned by a user, or fetch the user object with your upload. Run the application demo and look at the swagger documentation to see how.

Meta information

Models can have a special _meta field, which can customize settings about how cruddie-mock handles the model.

Right now, the only option available is count, which will change the number of results generated, instead of using the default. There is an example in the uploads model in the applications example.

Node API?

The module doesn't have a nodejs API, at least not yet. This is a planned feature, but I have no estimate for when it might be implemented.


The short answer is, send a PR! There are plenty of guides online to help you do this if you're new to it. I don't have any hard-and-fast rules - just please try to write tests if you are adding complex logic. I'm sure we can figure out a way to get your changes in.

Publishing new versions

This is mainly a note for myself, and any other contributors that might come along. Publishing is currently a manual process. Run the following commands, filling in details as needed.

npm version [patch|minor|major] -m "This is what we did"
git push && git push --tags

After this, please fill out the release notes on github. (Yes, manually. Sorry!)

A few words on testing...

This is the first personal project I've ever put effort into writing tests for. They probably are not super great, but my hope is that they will give contributors some confidence in their changes.

That said, I am not a firm believer in 100% test coverage, nor in complicating code to write better unit tests.

Don't let tests hold you up from submitting a PR! Whether you feel like some are missing, or you have tests failing for no reason - just note it in the PR and we'll get things working. My tests may need to be rewritten, or scrapped completely.

Modules we use and love

  • json-server: Great little script that creates express-friendly CRUD endpoints for a given object or json file.
  • faker.js: Has a ton of methods to create believable fake data.
  • swagger-ui: Functional UI around the OpenAPI specification, makes testing APIs simple and intuitive.


This software is released under the MIT license, detailed in the LICENSE file. Note that included modules such as swagger-ui, faker.js, and json-server may use separate licenses, such as the Apache license.


Node module for quickly spinning up CRUD APIs with mock data based on json model schemas.







No packages published