Json4Img REST API

This is simple and lightweight Java REST API application for local development (sandbox) which does simple things:

• writes PNG image file from JSON
• reads a PNG/JPG image to JSON

It is not complicated. It will follow KISS principle: keep it simple and stupid.

REST API is used for cross-platform compatibility: just run as standalone service on a any host and call it on port like 8080.
Because of that there is useful option to be supporting backend microservice (Docker container for instance) to produce and/or read image(s).

Used technologies

This Java app runs Bootique framework. This framework supports Environment variables and YML config files as well.

File storage

It is assumed there are IN and OUT:

• IN is sharedDir
• OUT is outputDir

Application will read images from sharedDir (IN) by a relative path and respond json for them.
And application will write image files into outputDir (OUT).

IN and OUT may be configured to point the same directory.

How is to run on Java

Build:

Build

mvn clean package

First Run

Configure file storage

Export IN and OUT into environment variables in Terminal.
Do run following shell script for demo run: project directory will be properly configured as file storage.

source ./use-pwdfs.sh

Run app

then run Java app:

java -Dbq.trace -jar json4img-rest/target/json4img-rest-1.0.jar --server --local

Open browser

Check in browser it works:

http://127.0.0.1:8080/json4img

Make first requests

POST to obtain json response for an image file on demo IN relative path /samples/sample.png:

curl -X POST -v -H "Content-Type: application/json" --data "{\"path\":\"/samples/sample.png\"}" http://127.0.0.1:8080/json4img/json

POST json for an image file (for demo it will be wrotten into ./output/example.png):

curl -X POST -H "Content-Type: application/json" -d @./samples/image.json http://127.0.0.1:8080/json4img/image

How is to run with Docker

initialize

m2 is local volume for Maven repository purposes.

docker volume create m2

fill vars in .env file

There is an example which from is good to start.

cp env.template .env

Mount volumes for file storage IN=${IMAGES_DIR} and OUT=${OUTPUT_DIR}.

How is to build

compile & build Java code

docker-compose run build-code

build Docker images:

docker-compose build

Run REST API service:

Run

docker-compose up json4img-rest

or in detached mode

docker-compose up -d json4img-rest

Preferences

Have a look at ./json4img-rest/src/main/resources/com/github/vitalz/jrest/json4img/server.yml YML as an example for custom config.

Jetty context and port

Jetty prefs are under jetty prefix.

File storage

File storage is in YML file under fs.

Environment variables

Such options may be declared for Bootique app via environment variables by exporting them in shell like in an example:

export JETTY_CONTEXT=/json4img/rest
export FS_SHAREDDIR=/opt/json4img/images
export FS_OUTPUTDIR=/opt/json4img/output

Run with custom preferences declared in its own YML config:

java -Dbq.trace -jar json4img-rest/target/json4img-rest-1.0.jar --server --config=/Users/vitalz/myjson4img.yml