2 unstable releases
0.2.0 | Jan 27, 2021 |
---|---|
0.1.0 | Jan 21, 2021 |
#801 in HTTP server
27KB
444 lines
jsonox 🛰
CLI based RESTful JSON server + store written in Rust.
Features 🚀
- Setup API endpoints on any route by simply POSTing
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 thejson_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.
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
-
Use cargo install:
cargo install jsonox
Or Build From Source
-
Clone the repository and run:
cargo build --lock --release
-
Compiled binary will be located at
target/release/jsonox
Initial Setup (when installing from binary/source)
-
Set executable permission:
chmod +x jsonox
-
Copy binary inside your
$PATH
directory (optional):cp jsonox ~/.local/bin/ #for linux
Usage 📡
Run the server via the CLI, then setup REST API endpoints or use in 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:
jsonox
-
Specify custom bind address:
jsonox -b localhost:7000
- Use
-b
or--bind-addr
- Address format:
<IP:PORT>
- Use
-
Disable logging:
jsonox --quiet
- Use
-q
or--quiet
for quiet mode.
- Use
-
Use ReadOnly mode:
jsonox --read-only
- Use
-r
or--read-only
for read-only mode.
- Use
-
View help and guide:
jsonox --help
- Use
-h
or--help
for help.
- Use
REST API (normal mode)
Construct REST API endpoints on arbitrary routes in the following way(s):
-
POST or PUT the following to
/pets/cat
:{ "cute": true }
-
Then GET at
/pets/cat
will receive:{ "cute": true }
-
Similarly you can DELETE data stored at
/pets/cat
, this will also receive:{ "cute": true }
-
The above requests will setup files under
./jsonox_data
with the following structure:- pets/ - cat/ - index.json
-
GET
on root endpoint/
will display all active endpoints:{ "active_paths": ["pets/cat"] }
You can also setup your own API by creating files under ./jsonox_data
in the structure similar as above:
- pets/
- dog/
- index.json
- cat/
- index.json
- index.json
- toys/
- doll/
- index.json
-
Then
GET
on/
will show active endpoints:{ "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
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
:- 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
, anddelete.json
, instead ofindex.json
. get.json
will contain the response body for GET requests to that path. Similarlypost.json
,put.json
, anddelete.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.
- In Read Only mode we create files like
-
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 otherget.json
,post.json
etc files created by you. -
Similar to normal mode
GET
on/
will show active endpoints:{ "active_paths": ["pets", "pets/cat", "pets/dog", "toys/doll"] }
Dependencies
~24–36MB
~630K SLoC