Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kjdev/jq-api
API system with JSON files and jq filters
https://github.com/kjdev/jq-api
jq nginx
Last synced: 25 days ago
JSON representation
API system with JSON files and jq filters
- Host: GitHub
- URL: https://github.com/kjdev/jq-api
- Owner: kjdev
- License: mit
- Created: 2022-07-12T03:42:09.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2022-08-05T03:46:54.000Z (over 2 years ago)
- Last Synced: 2024-11-18T00:52:35.786Z (about 2 months ago)
- Topics: jq, nginx
- Language: Shell
- Homepage:
- Size: 34.2 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
jq API
======
API system with JSON files and [jq](https://stedolan.github.io/jq) filters.
Required Commands
-----------------
- bash
- jq
- nginx ([jq module](https://github.com/kjdev/nginx-jq))
Build Docker image
------------------
Build the Docker image.
``` sh
$ docker build -t ghcr.io/kjdev/jq-api .
```
A JSON file of configuration and data is also required to run.
> ``` dockerfile
> WORKDIR /app
> ONBUILD COPY . /app/
> ONBUILD RUN /usr/local/bin/jq-api generate cli \
> && /usr/local/bin/jq-api generate server
> ```
>
> Place the files in WORKDIR (/app) or
> create a Docker image for execution with ONBUILD.
Configuration
-------------
config.json:
``` json
{
"json": "[JSON FILEPATH]",
"library_path": "[JQ LIBRARY PATH]",
"arguments": {
"[VARIABLE NAME]": {
"pattern": "[VARIABLE PATTERN]"
},
},
"routes": {
"[API PATH]": {
"parameters": [
"[VARIABLE NAME]"
],
"filter": "[JQ FILTER]"
},
},
"settings": {
"cli": {
"options": "[JQ OPTIONS FOR CLI]"
},
"server": {
"cors": {
"origin": "[NGINX CORS ORIGIN]",
"methods": "[NGINX CORS METHODS]",
"headers": "[NGINX CORS HEADERS]"
},
"ssl": {
"certificate": "[NGINX CERTIFICATE FILE]",
"certificate_key": "[NGINX_CERTIFICATE KEY FILE]"
},
"cache": {
"path": "[NGINX CACHE PATH]",
"time": "[NGINX CACHE TIME]",
"max_size": "[NGINX CACHE MAXIMUM SIZE]"
},
"error": {
"filter": "[JQ FILTER FOR SERVER ERROR]"
}
}
}
}
```
### json
The `json` key sets the JSON file that will serve as the data source.
``` json
{
"json": "./path/to/data.json"
}
```
> Relative paths are converted to absolute paths at runtime
> using the `realpath` command.
### library_path
The `library_path` key sets the module search path at jq runtime.
``` json
{
"library_path": "./path/to/dir"
}
```
> Relative paths are converted to absolute paths at runtime
> using the `realpath` command.
If there is no module file, it may be left unset.
### arguments
The `arguments` objec sets all variables used at jq runtime.
``` json
{
"arguments": {
"name": {}
}
}
```
A variable object can set the pattern of the variable with the `pattern` key.
``` json
{
"arguments": {
"name": {
"pattern": "number"
}
}
}
```
Possible values are `number`, `json`, and regular expressions.
The value of pattern is used by bash for regular expression comparison
during command line processing.
``` bash
if [[ ! "${data}" =~ ^(${regex})$ ]]; ..
```
Value handling:
- `number`: `[1-9][0-9]*`
- `json`: `{.*}`
- regex: `regex`
- not specified: `.*`
### routes
The `routes` object sets the API endpoints.
The `filter` key in the endpoint object sets the filter at jq runtime.
``` json
{
"routes": {
"endpoint": {
"filter": "."
}
}
}
```
The `parameters` key of the endpoint object sets variables to be used during
at jq runtime.
The values must be set in the arguments object.
``` json
{
"routes": {
"endpoint": {
"parameters": [
"id"
],
"filter": ".[] | select(.id == $id)"
}
}
}
```
Set variables to be used by enclosing them in braces ({}) in the endpoint.
``` json
{
"routes": {
"id/{id}": {
"filter": ".[] | select(.id == $id)"
}
}
}
```
### settings
The `settings` object can be used to configure additional
command line or server settings.
The `cli.options` object allows you to set jq options for command line runtime.
``` json
{
"settings": {
"cli": {
"options": "-c -R"
}
}
}
```
The `server.cors` object can set CORS response headers.
``` json
{
"settings": {
"server": {
"cors": {
"origin": "^https?://localhost",
"methods": "GET",
"headers": "Origin",
"credentials": true
}
}
}
}
```
- origin: Output `Access-Control-Allow-Origin` header matching
the regular expression matching `$http_origin` (or `*` if not set).
- methods: Value of the `Access-Control-Allow-Methods` header
(or `*` if not set).
- headers: value of the `Access-Control-Allow-Headers` header
(or `*` if not set)
- credentials: If true, output the `Access-Control-Allow-Credentials: true`
header.
The `server.ssl` object can set HTTPS.
``` json
{
"settings": {
"server": {
"ssl": {
"cert": "/path/to/cert.pem",
"key": "/path/to/cert-key.pem"
}
}
}
}
```
- cert: Specifies a file with the certificate in the PEM format.
- key: Specifies a file with the secret key in the PEM format.
The `server.cache` object can set cache.
``` json
{
"settings": {
"server": {
"cache": {
"path": "/dev/shm/nginx",
"time": "24h",
"max_size": "10m"
}
}
}
}
```
- path: Specifies the directory to store cache files
- time: Specifies the cache time
- max_size: Specifies the maximum capacity of the cache.
The `server.error` object allows you to configure what to do in case of
server errors.
``` json
{
"settings": {
"server": {
"error": {
"filter": "{\"code\":\"UNHANDLED_MATCH\",\"message\":\"Unhandled match path\"}"
}
}
}
}
```
Environment variable
--------------------
| name | default value | description |
|----------------------|-------------------|-----------------------------------|
| JQ_API_CONFIG | config.json | configuration file |
| JQ_API_WORKING_DIR | /var/local/jq-api | work data output directory |
| JQ_API_CLI_SCRIPT | cli.sh | command line script file |
| JQ_API_SERVER_CONFIG | server.conf | server (nginx) configuration file |
Example
-------
> other examples: [example](example/README.md)
Create a JSON data file.
``` sh
$ cat << EOF > data.json
[
{ "id": 1, "value": "first" },
{ "id": 2, "value": "second" },
{ "id": 3, "value": "third" }
]
EOF
```
Create configuration JSON file.
``` sh
$ cat << EOF > config.json
{
"json": "./data.json",
"arguments": {
"id": {}
},
"routes": {
"id": {
"parameters": [ "id" ],
"filter": ".[] | if \$id != \"\" then select(.id == (\$id|tonumber)) else . end"
},
"id/{id}": {
"filter": ".[] | select(.id == (\$id|tonumber))"
}
},
"settings": {
"cli": { "options": "-c" }
}
}
EOF
```
Place the file in WORKDIR and execute it on the command line.
``` sh
$ : id
$ docker run --rm -v $PWD:/app ghcr.io/kjdev/jq-api cli id -d id=1
{"id":1,"value":"first"}
$ : id/{id}
$ docker run --rm -v $PWD:/app ghcr.io/kjdev/jq-api cli id/2
{"id":2,"value":"second"}
```
Place a file in WORKDIR to start the API server.
``` sh
$ docker run --rm --name app -d -p 80:80 -v $PWD:/app ghcr.io/kjdev/jq-api server
```
Access the API server.
``` sh
$ : id
$ curl -G localhost/id -d id=2
{"id":2,"value":"second"}
$ : id/{id}
$ curl -G localhost/id/3
{"id":3,"value":"third"}
```
Stop the API server.
``` sh
$ docker stop app
```