Node module for quickly spinning up CRUD APIs with mock data based on json model schemas.
Switch branches/tags
Nothing to show
Clone or download

README.md

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, check out the live demo. This is powered by the application example.

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.

Options

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 0.0.0.0, 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

Address

Key Example Description
{{address.zipCode}} 86966 zipCode object.
{{address.city}} 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.
{{address.country}} 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.

Commerce

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.

Company

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.
{{company.bs}} 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.

Database

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

Date

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.

Finance

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.

Hacker

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.

Image

Key Example Description
{{image.image}} http://lorempixel.com/640/480/abstract image object.
{{image.avatar}} https://s3.amazonaws.com/uifaces/faces/twitter/charliegann/128.jpg avatar object.
{{image.imageUrl}} http://lorempixel.com/640/480 imageUrl object.
{{image.abstract}} http://lorempixel.com/640/480/abstract abstract object.
{{image.animals}} http://lorempixel.com/640/480/animals animals object.
{{image.business}} http://lorempixel.com/640/480/business business object.
{{image.cats}} http://lorempixel.com/640/480/cats cats object.
{{image.city}} http://lorempixel.com/640/480/city city object.
{{image.food}} http://lorempixel.com/640/480/food food object.
{{image.nightlife}} http://lorempixel.com/640/480/nightlife nightlife object.
{{image.fashion}} http://lorempixel.com/640/480/fashion fashion object.
{{image.people}} http://lorempixel.com/640/480/people people object.
{{image.nature}} http://lorempixel.com/640/480/nature nature object.
{{image.sports}} http://lorempixel.com/640/480/sports sports object.
{{image.technics}} http://lorempixel.com/640/480/technics technics object.
{{image.transport}} http://lorempixel.com/640/480/transport transport object.
{{image.dataUri}} [Data URI goes here] A Data URI object.

Internet

Key Example Description
{{internet.avatar}} https://s3.amazonaws.com/uifaces/faces/twitter/j04ntoh/128.jpg avatar object.
{{internet.email}} Thurman_Howell@yahoo.com email object.
{{internet.exampleEmail}} Derrick.Blick@example.com exampleEmail object.
{{internet.userName}} Marge_Hettinger userName object.
{{internet.protocol}} https protocol object.
{{internet.url}} http://genoveva.net url object.
{{internet.domainName}} birdie.com domainName object.
{{internet.domainSuffix}} biz domainSuffix object.
{{internet.domainWord}} lacy domainWord object.
{{internet.ip}} 164.123.119.107 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.

Lorem

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.

Name

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.

Phone

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

Random

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}} http://lorempixel.com/640/480/food image object.
{{random.locale}} ko locale object.
{{random.alphaNumeric}} n alphaNumeric object.

System

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.

Contributing

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.

License

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.