Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nilaysavant/jsonox
CLI based JSON server + store for mocking REST APIs
https://github.com/nilaysavant/jsonox
actix actix-web cli-app json json-api json-server json-store mock-server rest rest-api restful-api rust rust-lang
Last synced: 7 days ago
JSON representation
CLI based JSON server + store for mocking REST APIs
- Host: GitHub
- URL: https://github.com/nilaysavant/jsonox
- Owner: nilaysavant
- License: mit
- Created: 2021-01-19T10:58:08.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2021-01-27T03:36:52.000Z (about 4 years ago)
- Last Synced: 2025-02-01T16:39:50.695Z (7 days ago)
- Topics: actix, actix-web, cli-app, json, json-api, json-server, json-store, mock-server, rest, rest-api, restful-api, rust, rust-lang
- Language: Rust
- Homepage:
- Size: 57.6 KB
- Stars: 6
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# jsonox 🛰 
CLI based RESTful JSON server + store written in Rust.
## Features 🚀
- Setup **API endpoints** on **any route** by simply **POST**ing `JSON` to that route.
- Endpoints support **GET** for fetching and **DELETE** for deleting stored JSON along with **POST** or **PUT**.
- **JSON** data is stored as `*.json` files under the `jsonox_data` dir.
- View all **active endpoints** on the root (`/`) path.
**[DISCLAIMER: This program is designed for development purposes. Use in production at your own risk!]**
## Installation 🔧
You can install in 3 ways: Using pre-compiled binary, from Crate or by manually building from source using rust tool-chain. Give necessary executable permissions for the binary and if building from source.
### Pre-compiled Binary
- Download binary for your platform from the latest [release](https://github.com/nilaysavant/jsonox/releases).
| Binary | Platform |
| -------------------- | ---------------------------------------------------------- |
| jsonox-linux-amd64 | 64-bit Linux (Ubuntu, Debian etc) |
| jsonox-macos-amd64 | 64-bit Mac OS |
| jsonox-win-amd64.exe | 64-bit Windows 7+ |
| jsonox-linux-armv7 | ARMv7 Linux: Raspberry PI, Debian, Ubuntu |
| jsonox-linux-armv6 | (Untested!) ARMv6 Linux: Raspberry PI Zero, Debian, Ubuntu |
### Install from [Crate](https://crates.io/crates/jsonox)
- Use cargo install:
```bash
cargo install jsonox
```
### Or Build From Source
- Clone the repository and run:
```bash
cargo build --lock --release
```
- Compiled binary will be located at `target/release/jsonox`
### Initial Setup (when installing from binary/source)
- Set executable permission:
```bash
chmod +x jsonox
```
- Copy binary inside your `$PATH` directory (optional):
```bash
cp jsonox ~/.local/bin/ #for linux
```
## Usage 📡
Run the server via the **CLI**, then setup **REST API endpoints** or use in [Read Only mode](#read-only-mode).
### Command line (CLI)
Note: In the following examples you may need to use `./jsonox` if using local binary.
- Simple server with logging:
```bash
jsonox
```
- Runs at:
- http://localhost:8080/
- http://127.0.0.1:8080/
- http://0.0.0.0:8080/
- Specify custom bind address:
```bash
jsonox -b localhost:7000
```
- Use `-b` or `--bind-addr`
- Address format: ``
- Disable logging:
```bash
jsonox --quiet
```
- Use `-q` or `--quiet` for quiet mode.
- Use **ReadOnly** mode:
```bash
jsonox --read-only
```
- Use `-r` or `--read-only` for [read-only mode](#read-only-mode).
- View help and guide:
```bash
jsonox --help
```
- Use `-h` or `--help` for help.
### REST API (normal mode)
Construct **REST API** endpoints on **arbitrary routes** in the following way(s):
- **POST** or **PUT** the following to `/pets/cat`:
```json
{ "cute": true }
```
- Then **GET** at `/pets/cat` will receive:
```json
{ "cute": true }
```
- Similarly you can **DELETE** data stored at `/pets/cat`, this will also receive:
```json
{ "cute": true }
```
- The above requests will setup files under `./jsonox_data` with the following structure:
```bash
- pets/
- cat/
- index.json
```
- `GET` on root endpoint `/` will display all active endpoints:
```json
{ "active_paths": ["pets/cat"] }
```
You can also setup your own API by creating files under `./jsonox_data` in the structure similar as above:
```bash
- pets/
- dog/
- index.json
- cat/
- index.json
- index.json
- toys/
- doll/
- index.json
```
- Then `GET` on `/` will show active endpoints:
```json
{ "active_paths": ["pets", "pets/cat", "pets/dog", "toys/doll"] }
```
- You can then do **GET**,**POST**, **PUT** and **DELETE** similarly, on the endpoint paths above.
NOTE: **POST** and **PUT** are **interchangeable** and **work exactly the same in this mode**. This is due to the paths referred to being explicitly specific. To allow for different responses in case of POST and PUT, please consider using the [Read Only mode](#read-only-mode).
### Read Only Mode
In this mode, jsonox _only reads the json files stored_ and **does NOT create/delete** them in case of **POST/DELETE** unlike in the normal mode explained above. This is useful when you **only need to simulate API responses** and when your back-end does not strictly follow the REST standards. You can also record the `./jsonox_data` in your version control to store your API response structures as it won't change based on the simulations/testing in this mode.
- Start by creating files in `./jsonox_data`:
```bash
- pets/
- dog/
- get.json
- post.json
- cat/
- get.json
- get.json
- delete.json
- toys/
- doll/
- get.json
- post.json
- put.json
- delete.json
```
- In **Read Only** mode we create files like `get.json`, `post.json`, `put.json`, and `delete.json`, instead of `index.json`.
- `get.json` will contain the **response body** for **GET** requests to that path. Similarly `post.json`, `put.json`, and `delete.json` will contain the **response body** for **POST**, **PUT**, and **DELETE** requests to that path respectively.
- Thus as per above structure:
- `/pets` will have **GET** and **DELETE** only.
- `/pets/cat` will have **GET** only.
- `/pets/dog` will have **GET** and **POST** only.
- `/toys/doll` will have **GET**, **POST**, **PUT** and **DELETE**.
- The files and paths created by you will not be deleted even if you do a **DELETE** on a path.
- If you change modes in between, and do a **DELETE** in **normal mode**, this will _only delete `index.json` files at the respective paths_ and NOT delete the other `get.json`, `post.json` etc files created by you.
- Similar to normal mode `GET` on `/` will show active endpoints:
```json
{ "active_paths": ["pets", "pets/cat", "pets/dog", "toys/doll"] }
```