matiasiacono/mock-api repository overview

Mock API is a free, open-source tool for creating mock HTTP APIs for development and testing. Keep building when a third-party API is unavailable, incomplete, or difficult to reproduce in a test environment.

Define endpoints and responses, simulate delays and errors, and update your mocks while the application is running.

Features include:

• A web console with visual configuration and an expert JSON/YAML editor.
• Configurable routes, HTTP methods, response bodies, headers, and status codes.
• Response sequences, request matching, and file-based data sources.
• A built-in request tester and request history.
• Configuration through the standard .mockapi-config file.

The Docker image includes Node.js and the application dependencies. You only need Docker installed on your computer.

To try the bundled sample API, run:

docker run --rm --name mockapi-quickstart -p 127.0.0.1:8001:8001 matiasiacono/mock-api:3.0.0

Docker downloads the image from Docker Hub automatically if it is not already available locally. If you have already pulled it, the same command starts it. No source-code checkout or compose.yaml file is required.

Try the bundled endpoint at http://localhost:8001/data⁠. Press Ctrl+C to stop and remove the quick-start container.

This starts the API with its bundled sample configuration. To use the web console in Docker, supply your own .mockapi-config with an admin token as described below. Mounting its directory also preserves your configuration changes when the container is replaced.

To run Mock API with the web console and persistent configuration, stop the quick-start container first to free port 8001, then:

1. Create a directory named mock-workspace and save this file inside it as .mockapi-config:

   port: 8001
   enableCors: true
   
   admin:
     enabled: true
     token: "REPLACE-WITH-YOUR-OWN-RANDOM-TOKEN"
   
   endpoints:
     /hello:
       get:
         responseStatus: 200
         response:
           message: Hello from Mock API
   

   Copy

   Replace the token placeholder with a long random secret. You will enter this same value when connecting to the web console. Each developer should use their own token.

2. Start the image with that directory mounted. Replace WORKSPACE_PATH with the absolute path to your mock-workspace directory, for example C:/Users/yourname/mock-workspace on Windows or /home/yourname/mock-workspace on Linux:

   docker run --rm --name mockapi -p 127.0.0.1:8001:8001 --mount "type=bind,source=WORKSPACE_PATH,target=/workspace" matiasiacono/mock-api:3.0.0 node main.js --config /workspace/.mockapi-config
   

   Copy

3. Open the web console at http://localhost:8001/__mockapi/ui/⁠ and enter your configured admin token. Keep the command running while you use the application; press Ctrl+C to stop it.

Try the sample endpoint at http://localhost:8001/hello⁠:

{
  "message": "Hello from Mock API"
}

Changes saved through the console are written to mock-workspace/.mockapi-config and survive container replacement. Most configuration changes apply automatically; changes to the listening address, port, or TLS require a restart.

Mount the whole workspace directory so the console can save configuration changes. On Linux, ensure the container's node user, UID 1000, can write to that directory.

Docker Compose is an optional alternative that saves the startup settings in a file. To use it, stop the container started with docker run first, then:

1. Create a compose.yaml file alongside the same mock-workspace directory:

   services:
     mockapi:
       image: matiasiacono/mock-api:3.0.0
       ports:
         - "127.0.0.1:8001:8001"
       volumes:
         - ./mock-workspace:/workspace
       command:
         - node
         - main.js
         - --config
         - /workspace/.mockapi-config
   

   Copy

   Your directory structure should be:

   your-project/
   ├── compose.yaml
   └── mock-workspace/
       └── .mockapi-config
   

   Copy

2. Start the application from the directory containing compose.yaml:

   docker compose up -d
   

   Copy

   Docker downloads the image automatically.

The web console is available at the same URL and uses the same admin token and configuration file.

View logs or stop the application with:

docker compose logs -f
docker compose down

The examples pin version 3.0.0. You can also use matiasiacono/mock-api:latest to select the latest published release.

Source code, documentation, and issue reporting: github.com/MatiasIac/mockapi⁠.