Projects, files and Git

A project is one mock API: its endpoints, flows and settings, served on one port and saved as one JSON file. This page covers managing projects, where the files are, what is inside them, and how to share them through export, import and Git.

Work with several projects

Click the project switcher at the top of the side panel to see all your projects. Each entry shows the project's port and whether its server is running. Select one to switch to it.

Every project has its own server, port and request log, so several can run at the same time: a users API on 8080 and a payments API on 8081, for example. Switching projects does not stop a running server.

Create a project

Click the project switcher and choose New project.
Type a Project name, such as Payments API.
Check the Port. Mock Studio suggests a free one. Pick a number from 1024 to 65535 that nothing else uses.
Select Create.

The new project is empty. Add endpoints with +, or bring them in with Import. If the port you typed belongs to another project, the next free number is used.

If you have no projects at all, the main area shows Create your first mock API with three buttons: Create a project, Import a Postman collection and Import OpenAPI / Swagger.

Rename, duplicate, export or delete

Open the ⋯ menu beside the project switcher.

Menu item	What it does
Rename	Changes the display name. The port, endpoints and saved file stay the same.
Duplicate	Makes a full copy, with endpoints, settings and flows, named with `(copy)`, on the next free port.
Export to file	Saves the project as a `.json` file wherever you choose.
Delete	Removes the project and its file.

Duplicate is a safe way to try changes: experiment on the copy and delete it afterwards.

DANGER

Delete stops the project's server and removes the project, all its endpoints and flows, and its file from disk. Mock Studio asks you to confirm, and it cannot be undone. Use Export to file first if you might want it back.

Where the files are

Mock Studio saves each project automatically as you edit, in a MockStudio/projects folder inside your Documents folder.

Install	Projects folder
Linux, `.deb` package	`~/Documents/MockStudio/projects`
Any install	Shown by Copy projects folder path in Settings

To get the exact folder on your computer, open Settings in the rail and select Copy projects folder path, then paste it into your file manager or terminal. The path of the current project's file is also shown under Storage at the bottom of the Project section.

Each file is named after the project, followed by a short id:

text

~/Documents/MockStudio/projects/
  my-first-mock-api-1a2b3c4d.json
  payments-api-9f8e7d6c.json

The file name is set when the project is first saved and does not change when you rename the project.

Things to know:

Mock Studio reads every .json file in the folder when it starts. A file it cannot read is skipped.
Each save writes the whole file, through a temporary .tmp file that is then renamed, so a crash cannot leave a half-written project.
If your Documents folder is synced by a cloud service, the project files are synced with it.
The request log and flow results are not saved anywhere.

The file format

A project file is plain, indented JSON that you can read, compare and edit. This is a small but complete project with one endpoint that uses conditional rules:

json

{
  "mockstudioVersion": 1,
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Shop API",
  "description": "",
  "port": 8080,
  "corsEnabled": true,
  "proxyBaseUrl": "",
  "recordProxy": false,
  "globalDelayMs": 0,
  "globalHeaders": {
    "Cache-Control": "no-store"
  },
  "endpoints": [
    {
      "id": "7c1e3f50-2b4d-4e6a-9f8b-1a2c3d4e5f60",
      "name": "Get order",
      "method": "get",
      "path": "/orders/:orderId",
      "enabled": true,
      "strategy": "rules",
      "responses": [
        {
          "id": "0d9c8b7a-6f5e-4d3c-8b2a-190817263544",
          "label": "Not found",
          "statusCode": 404,
          "bodyType": "json",
          "body": "{\n  \"error\": \"order_not_found\"\n}",
          "headers": {},
          "conditions": [
            {
              "source": "pathParam",
              "key": "orderId",
              "operator": "equals",
              "value": "999"
            }
          ],
          "weight": 1,
          "delayMs": null,
          "fault": "none"
        },
        {
          "id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
          "label": "Found",
          "statusCode": 200,
          "bodyType": "json",
          "body": "{\n  \"id\": \"{{params.orderId}}\",\n  \"status\": \"shipped\"\n}",
          "headers": {
            "X-Request-Id": "{{uuid}}"
          },
          "conditions": [],
          "weight": 1,
          "delayMs": 250,
          "fault": "none"
        }
      ],
      "defaultDelayMs": 0,
      "jitterMs": 0,
      "requireAuth": false,
      "authHeader": "Authorization",
      "description": "",
      "folder": "Orders"
    }
  ]
}

Project fields

Field	Meaning	In the app
`mockstudioVersion`	Format version, `1`
`id`	The project's unique id
`name`, `description`	Display name and description	Project switcher
`port`	Port the server listens on	Port
`corsEnabled`	Whether CORS headers are sent	Enable CORS
`proxyBaseUrl`	Real API for unmatched requests; empty for none	Forward unmatched requests to (base URL)
`recordProxy`	Whether proxied replies are recorded	Record proxied responses
`globalDelayMs`	Delay added to every response, in ms	Global delay (ms)
`globalHeaders`	Headers added to every response	Global headers
`endpoints`	The list of endpoints, in list order	Endpoints
`flows`	The list of flows; left out when there are none	Flows

Endpoint fields

Field	Meaning and values
`id`	The endpoint's unique id
`name`	Endpoint name
`method`	`any`, `get`, `post`, `put`, `patch`, `delete`, `head` or `options`
`path`	Path template, such as `/orders/:orderId`
`enabled`	`false` when the endpoint is disabled
`strategy`	`single`, `rules`, `sequence` or `random`
`responses`	The list of responses, in order
`defaultDelayMs`	Base delay (ms)
`jitterMs`	Random jitter (ms)
`requireAuth`	Whether an auth header is required
`authHeader`	Required header name
`description`	Description / notes
`folder`	Folder path, with `/` between levels; left out at the top level

Response fields

Field	Meaning and values
`id`	The response's unique id
`label`	Label
`statusCode`	Status
`bodyType`	`json`, `text`, `html`, `xml` or `none` (shown as Empty)
`body`	The body as one string; line breaks are written as `\n`
`headers`	Response headers, as name and value pairs
`conditions`	Conditions for Conditional rules; empty for a fallback
`weight`	Weight for Random / weighted
`delayMs`	Delay override (ms), or `null` to use the endpoint's base delay
`fault`	`none`, `connectionReset`, `emptyResponse`, `malformedBody` or `hang`

Each condition has four fields:

Field	Values
`source`	`query`, `header`, `pathParam`, `bodyJson` or `method`
`key`	The parameter, header or field name
`operator`	`equals`, `notEquals`, `contains`, `exists`, `regex`, `greaterThan` or `lessThan`
`value`	The value to compare with

Flow fields

A flow in the flows list has id, name, mode (sequential for One by one, parallel for All at once), virtualUsers, iterations, durationSec, rampUpSec, thinkTimeMs, targetUrl, stopOnFailure and steps. Each step has id, name, method, path, headers, body, expectStatus, extract and enabled. Flows explains each setting.

Good to know

You can edit a project file by hand, but do it while Mock Studio is closed. The app reads files only when it starts and writes the whole file on every change, so an edit made while it is open is overwritten.

Export and import

Export writes a copy of a project to a file you choose. Import loads such a file as a new project.

Open the ⋯ menu beside the project switcher and choose Export to file.
Choose a folder and a name. Mock Studio suggests the project name with .mockstudio.json on the end, such as shop-api.mockstudio.json.

To load an exported file:

Select Import in the rail, then Mock Studio project file.
Pick the .json file.

The imported project is a separate copy. It gets (imported) added to its name, a new id, and the next free port if its port is taken. Importing the same file twice gives two projects; it never merges into or overwrites an existing one.

Keep mocks in Git

Because a project is a readable text file, it fits well in version control. There are two ways to do it.

Export into your app's repository

This suits a mock that belongs with one codebase.

Export the project into the repository, for example to mocks/shop-api.mockstudio.json.

Commit the file.

bash

git add mocks/shop-api.mockstudio.json
git commit -m "Add Shop API mock"

A teammate pulls the repository and uses Import, then Mock Studio project file, to load it.

When the mock changes, export again over the same file and commit. Teammates import the new version and delete their old copy.

Put the projects folder itself under Git

This suits a team that shares a set of mocks. Everyone's edits are saved straight into the repository's working folder.

bash

cd ~/Documents/MockStudio/projects
git init
git add *.json
git commit -m "Add mock projects"

Add a .gitignore with the line *.tmp so that temporary save files are never committed.

To pick up a teammate's changes, close Mock Studio, run git pull, then open it again. Pulling while the app is open does not show the changes, and your next edit would overwrite the pulled file.

Check for secrets and personal data. Response bodies, headers and flow steps are stored as plain text. Recorded replies from a real API may hold real names, emails or tokens. See Proxy and record.
Check the proxy address. proxyBaseUrl is saved in the file. Clear it if the address should not be shared.
Expect ids in diffs. Each project, endpoint and response carries a generated id. They are stable, so normal edits change only the lines you touched.

Projects, files and Git ​

Work with several projects ​

Create a project ​

Rename, duplicate, export or delete ​

Where the files are ​

The file format ​

Project fields ​

Endpoint fields ​

Response fields ​

Flow fields ​

Export and import ​

Keep mocks in Git ​

Export into your app's repository ​

Put the projects folder itself under Git ​

Before you commit or share ​

Next steps ​