Skip to content

Latest commit

 

History

History
212 lines (146 loc) · 6.11 KB

README.md

File metadata and controls

212 lines (146 loc) · 6.11 KB
Raw

jsonox 🛰 Build Release

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 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.

    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>

  • Disable logging:

    jsonox --quiet
    • Use -q or --quiet for quiet mode.

  • Use ReadOnly mode:

    jsonox --read-only

  • View help and guide:

    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:

    { "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, 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:

    { "active_paths": ["pets", "pets/cat", "pets/dog", "toys/doll"] }