Skip to content

R3 Mimic Server

Radically Reckless Reflector (R3) of HTTP responses

What is the R3 Mimic Server

The Radically Reckless Reflector (R3) Mimic Server is a HTTP stub server intended to mimic API responses from different systems.

It is intended to make Test-Driven Development easier by reducing dependencies on having access to end systems.

R3 Servers are intended to flexible enough to use for different API profiles. Each target system being mocked will have a profile of allowed requests and sample response data.

Mimic Modes

R3 servers currently support the following modes:

  • promiscuous mode reflects back any route that is requested.

  • This is the default when no profile is supplied.

  • file mode leverages folders and files to identify valid routes.

  • Folders can contain .json files to be used as responses.

  • mimic mode acts as a stub server for a given profile.

  • Requests must match supplied regex patterns and verbs.
  • Responses may supply example JSON or other output formats.

Getting Started

Installation

The r3mimic server requires python3.9+.

Install r3mimic with pip in a virtual environment. For example, on Linux and MacOS use:

python3 -m venv .venv
source .venv/bin/activate

Then to install the r3mimic module use:

pip install r3mimic

Note that access to the private Empowered Networks PEP503 server is required.

Checking the version

To verify that the installation was successful, run the following:

r3mimic --version

This should return the version number of the r3mimic install.

First run of r3mimic

To test out the r3mimic, run the following command:

r3mimic start

This runs in promiscuous mode by default on port 5000. To test it, go to the url http://127.0.0.1:5000/helloworld in a browser.

Replace helloworld with any route to see successful responses.

Changing the port

Add --port <PORT> to the command line to change the port number.

For example, use the following to change the port to 8088:

r3mimic start --port 8088

r3mimic modes

In addition to the default promiscuous mode, the following modes are also supported:

  • file mode for file-system driven routes, and
  • mimic mode for advanced configurations.

These modes can be specified on the CLI or via profiles.

File mode

File mode provides a quick way to run a server driven off of folders and files.

In this mode, folders off a given source directory represent valid routes. Files in these folders are used to respond to requests based on methods.

The server will detect folders and files that exist for each request. If changes are made to the file system, the server will automatically detect them without requiring restarting.

File mode quick start

To run the r3mimic server in file mode, use a command similar to the following:

r3mimic start --mode=file --src='./site' --prefix='api/v1'

This command would trigger the r3mimic server to use files found in the site directory path off the current directory. Routes would be prefixed with api/vi/.

It would respond to requests using the following format:

http://localhost:5000/api/v1/dirpath/filename

Where dirpath could be nested as many levels as needed, and filename corresponds to any files existing in the directory path.

File mode options

The following basic options are used by the r3mimic server in file mode:

  • src indicates the directory holding the response files (required)
  • prefix indicates the route prefix for responses (optional).
  • By default, src is treated as root / if prefix is not provided.
  • index_page indicates the accepted filenames to automatically load.
  • By default, index.html is used (for example, / treated as /index.html).
  • Multiple filenames can be provided using comma-separators.

Any directories created off the src directory are treated as routes.

Retrieving Files

Any files present will be served by the r3mimic server. This includes html files, image files, basically anything.

There are special filenames used to signify HTTP methods, as explained below.

JSON files

JSON files with the .json suffix are treated specially. If a url does not match any files, the file path will be checks to see if there is match when .json is added to the end.

For example, if there was a file called 123.json in a directory devices, the url /devices/123 would respond with the contents of 123.json as the JSON body.

HTTP Method Files

In file mode, special filenames are used to mimic responses to HTTP API methods such as GET, POST, PUT, PATCH and DELETE.

Filenames prefixed with r3mimic_<METHOD> will automatically be picked up and used as the response for a given method.

For example, r3mimic_get.json will be used as the JSON body for a response to a GET. If the file was in a directory called "devices", a GET to /devices would return the JSON.

These method files can be mixed with other files and JSON files.

Failed Responses

Any request that does not correspond to any existing folders or files will return an HTTP 404 error by default.

r3mimic profiles

Profiles provide a way to provide multiple settings using a profile name.

For example, the command:

r3mimic start --profile=systemx

Will initialize the server with configuration settings from the file systemx.yml.

The profile can either be a shorthand name or a full file path.

Named profiles

Names can be explicitly specified in the r3mimic_config.yml file in the profiles section. Or they can be implicit where .yml is appended to the name to create a file name to search for. By default the current directory is searched for profile files. Or the directories to search can be listed in the r3mimic_config.yml file using the profile_dirs setting in the profiles section.

Profile settings

Profiles provide a way to set more advanced settings beyond the options available in the CLI.

In addition to the mode, profiles can contain lists of endpoints, each with pointers to files to use for responses to specific HTTP methods.

Advanced features such as regex pattern matching for urls, paging options, and other query string features are also set through profiles.