File serving
Besides using the body editor, Mockoon allows you to serve different files for each route. File serving should be the preferred method when you want to send lots of data.
Using files
To serve a file, you must provide a path in the file input field:
💡 When a file path is provided, the body editor content will be ignored.
Absolute or relative paths
You can either provide an absolute path like /home/username/file.json or a relative path. Relative paths are resolved from the environment's file location. You can check the environment's file location by right-clicking on an environment en select "Show in folder" in the contextual menu:
💡 Relative file paths resolving is also supported by the CLI.
Templating
Templating is available in both the file content and the file input field.
File content templating
As for the body editor, templating will be parsed inside files for a limited set of MIME types (application/json, text/html, text/css, text/csv, application/javascript, application/typescript, text/plain, application/xhtml+xml, application/xml). You can use all the available templating helpers to generate dynamic mock data.
Templating can be disabled both for the body editor and the file content. Please refer to the templating documentation for more information.
⚡ A note on performances
Parsing the templating helpers inside big files can be a very intensive task (CPU and memory intensive). All the files in different formats than the one mentioned above will be streamed to improve performances.
If you need to send big files in one of the above formats but don't need to parse the templating, you can disable it in the route response settings. It will stream the file instead of parsing it and improve the performance.
File input templating
Templating is also supported directly in the file input field. It allows to dynamically generate the file path using helpers. Please refer to the templating documentation for more information.
⚠️ A note on security: When using templating helpers in the file input field, Mockoon will prevent path traversal attacks by disallowing escaping the current folder by passing ../ through the templating engine. The current folder is either the environment's file location for relative paths or the part of the path before the first template variable, e.g. in /home/username/{{queryParam 'filename'}}, the current folder is /home/username/ and passing ../ in the filename won't be allowed.
404 fallback
By default, Mockoon will return an error in the body when a file is not found. It will still keep the status code you set up on your route response. You can instead choose to automatically return a 404 by activating an option in the route response settings:
This option will also fall back to use the content present in the body editor.
Serving a range of bytes from a file
Mockoon supports the Range header for files that are not parsed by the templating engine or when the templating is disabled on the response (see above).
To use this feature, you must provide a Range header in your request. The header value must be in the form bytes=start-end where start and end are the byte positions of the file you want to return. For example, bytes=0-100 will return the first 100 bytes of the file.
The server will answer with a 206 Partial Content status code and the Content-Range header containing the range of bytes returned. If the range is invalid, the server will answer with a 416 Range Not Satisfiable status code.