{"id":23092644,"url":"https://github.com/kjdev/jq-api","last_synced_at":"2026-04-24T22:31:49.900Z","repository":{"id":44758965,"uuid":"512988534","full_name":"kjdev/jq-api","owner":"kjdev","description":"API system with JSON files and jq filters","archived":false,"fork":false,"pushed_at":"2022-08-05T03:46:54.000Z","size":35,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-01T22:44:21.184Z","etag":null,"topics":["jq","nginx"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kjdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-07-12T03:42:09.000Z","updated_at":"2022-08-04T08:46:15.000Z","dependencies_parsed_at":"2022-09-19T05:21:04.020Z","dependency_job_id":null,"html_url":"https://github.com/kjdev/jq-api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kjdev/jq-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kjdev%2Fjq-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kjdev%2Fjq-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kjdev%2Fjq-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kjdev%2Fjq-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kjdev","download_url":"https://codeload.github.com/kjdev/jq-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kjdev%2Fjq-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32243160,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jq","nginx"],"created_at":"2024-12-16T21:35:32.864Z","updated_at":"2026-04-24T22:31:49.884Z","avatar_url":"https://github.com/kjdev.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"jq API\n======\n\nAPI system with JSON files and [jq](https://stedolan.github.io/jq) filters.\n\nRequired Commands\n-----------------\n\n- bash\n- jq\n- nginx ([jq module](https://github.com/kjdev/nginx-jq))\n\nBuild Docker image\n------------------\n\nBuild the Docker image.\n\n``` sh\n$ docker build -t ghcr.io/kjdev/jq-api .\n```\n\nA JSON file of configuration and data is also required to run.\n\n\u003e ``` dockerfile\n\u003e WORKDIR /app\n\u003e ONBUILD COPY . /app/\n\u003e ONBUILD RUN /usr/local/bin/jq-api generate cli \\\n\u003e          \u0026\u0026 /usr/local/bin/jq-api generate server\n\u003e ```\n\u003e\n\u003e Place the files in WORKDIR (/app) or\n\u003e create a Docker image for execution with ONBUILD.\n\nConfiguration\n-------------\n\nconfig.json:\n\n``` json\n{\n  \"json\": \"[JSON FILEPATH]\",\n  \"library_path\": \"[JQ LIBRARY PATH]\",\n  \"arguments\": {\n    \"[VARIABLE NAME]\": {\n      \"pattern\": \"[VARIABLE PATTERN]\"\n    },\n  },\n  \"routes\": {\n    \"[API PATH]\": {\n      \"parameters\": [\n        \"[VARIABLE NAME]\"\n      ],\n      \"filter\": \"[JQ FILTER]\"\n    },\n  },\n  \"settings\": {\n    \"cli\": {\n      \"options\": \"[JQ OPTIONS FOR CLI]\"\n    },\n    \"server\": {\n      \"cors\": {\n        \"origin\": \"[NGINX CORS ORIGIN]\",\n        \"methods\": \"[NGINX CORS METHODS]\",\n        \"headers\": \"[NGINX CORS HEADERS]\"\n      },\n      \"ssl\": {\n        \"certificate\": \"[NGINX CERTIFICATE FILE]\",\n        \"certificate_key\": \"[NGINX_CERTIFICATE KEY FILE]\"\n      },\n      \"cache\": {\n        \"path\": \"[NGINX CACHE PATH]\",\n        \"time\": \"[NGINX CACHE TIME]\",\n        \"max_size\": \"[NGINX CACHE MAXIMUM SIZE]\"\n      },\n      \"error\": {\n        \"filter\": \"[JQ FILTER FOR SERVER ERROR]\"\n      }\n    }\n  }\n}\n```\n\n### json\n\nThe `json` key sets the JSON file that will serve as the data source.\n\n``` json\n{\n  \"json\": \"./path/to/data.json\"\n}\n```\n\n\u003e Relative paths are converted to absolute paths at runtime\n\u003e using the `realpath` command.\n\n### library_path\n\nThe `library_path` key sets the module search path at jq runtime.\n\n``` json\n{\n  \"library_path\": \"./path/to/dir\"\n}\n```\n\n\u003e Relative paths are converted to absolute paths at runtime\n\u003e using the `realpath` command.\n\nIf there is no module file, it may be left unset.\n\n### arguments\n\nThe `arguments` objec sets all variables used at jq runtime.\n\n``` json\n{\n  \"arguments\": {\n    \"name\": {}\n  }\n}\n```\n\nA variable object can set the pattern of the variable with the `pattern` key.\n\n``` json\n{\n  \"arguments\": {\n    \"name\": {\n      \"pattern\": \"number\"\n    }\n  }\n}\n```\n\nPossible values are `number`, `json`, and regular expressions.\n\nThe value of pattern is used by bash for regular expression comparison\nduring command line processing.\n\n``` bash\nif [[ ! \"${data}\" =~ ^(${regex})$ ]]; ..\n```\n\nValue handling:\n\n- `number`: `[1-9][0-9]*`\n- `json`: `{.*}`\n- regex: `regex`\n- not specified: `.*`\n\n### routes\n\nThe `routes` object sets the API endpoints.\n\nThe `filter` key in the endpoint object sets the filter at jq runtime.\n\n``` json\n{\n  \"routes\": {\n    \"endpoint\": {\n      \"filter\": \".\"\n    }\n  } \n}\n```\n\nThe `parameters` key of the endpoint object sets variables to be used during\nat jq runtime.\n\nThe values must be set in the arguments object.\n\n``` json\n{\n  \"routes\": {\n    \"endpoint\": {\n      \"parameters\": [\n        \"id\"\n      ],\n      \"filter\": \".[] | select(.id == $id)\"\n    }\n  } \n}\n```\n\nSet variables to be used by enclosing them in braces ({}) in the endpoint.\n\n``` json\n{\n  \"routes\": {\n    \"id/{id}\": {\n      \"filter\": \".[] | select(.id == $id)\"\n    }\n  } \n}\n```\n\n### settings\n\nThe `settings` object can be used to configure additional\ncommand line or server settings.\n\nThe `cli.options` object allows you to set jq options for command line runtime.\n\n``` json\n{\n  \"settings\": {\n    \"cli\": {\n      \"options\": \"-c -R\"\n    }\n  }\n}\n```\n\nThe `server.cors` object can set CORS response headers.\n\n``` json\n{\n  \"settings\": {\n    \"server\": {\n      \"cors\": {\n        \"origin\": \"^https?://localhost\",\n        \"methods\": \"GET\",\n        \"headers\": \"Origin\",\n        \"credentials\": true\n      }\n    }\n  }\n}\n```\n\n- origin: Output `Access-Control-Allow-Origin` header matching\n  the regular expression matching `$http_origin` (or `*` if not set).\n- methods: Value of the `Access-Control-Allow-Methods` header\n  (or `*` if not set).\n- headers: value of the `Access-Control-Allow-Headers` header\n  (or `*` if not set)\n- credentials: If true, output the `Access-Control-Allow-Credentials: true`\n  header.\n\nThe `server.ssl` object can set HTTPS.\n\n``` json\n{\n  \"settings\": {\n    \"server\": {\n      \"ssl\": {\n        \"cert\": \"/path/to/cert.pem\",\n        \"key\": \"/path/to/cert-key.pem\"\n      }\n    }\n  }\n}\n```\n\n- cert: Specifies a file with the certificate in the PEM format.\n- key: Specifies a file with the secret key in the PEM format.\n\nThe `server.cache` object can set cache.\n\n``` json\n{\n  \"settings\": {\n    \"server\": {\n      \"cache\": {\n        \"path\": \"/dev/shm/nginx\",\n        \"time\": \"24h\",\n        \"max_size\": \"10m\"\n      }\n    }\n  }\n}\n```\n\n- path: Specifies the directory to store cache files\n- time: Specifies the cache time\n- max_size: Specifies the maximum capacity of the cache.\n\nThe `server.error` object allows you to configure what to do in case of\nserver errors.\n\n``` json\n{\n  \"settings\": {\n    \"server\": {\n      \"error\": {\n        \"filter\": \"{\\\"code\\\":\\\"UNHANDLED_MATCH\\\",\\\"message\\\":\\\"Unhandled match path\\\"}\"\n      }\n    }\n  }\n}\n```\n\nEnvironment variable\n--------------------\n\n| name                 | default value     | description                       |\n|----------------------|-------------------|-----------------------------------|\n| JQ_API_CONFIG        | config.json       | configuration file                |\n| JQ_API_WORKING_DIR   | /var/local/jq-api | work data output directory        |\n| JQ_API_CLI_SCRIPT    | cli.sh            | command line script file          |\n| JQ_API_SERVER_CONFIG | server.conf       | server (nginx) configuration file |\n\nExample\n-------\n\n\u003e other examples: [example](example/README.md)\n\nCreate a JSON data file.\n\n``` sh\n$ cat \u003c\u003c EOF \u003e data.json\n[\n  { \"id\": 1, \"value\": \"first\" },\n  { \"id\": 2, \"value\": \"second\" },\n  { \"id\": 3, \"value\": \"third\" }\n]\nEOF\n```\n\nCreate configuration JSON file.\n\n``` sh\n$ cat \u003c\u003c EOF \u003e config.json\n{\n  \"json\": \"./data.json\",\n  \"arguments\": {\n    \"id\": {}\n  },\n  \"routes\": {\n    \"id\": {\n      \"parameters\": [ \"id\" ],\n      \"filter\": \".[] | if \\$id != \\\"\\\" then select(.id == (\\$id|tonumber)) else . end\"\n    },\n    \"id/{id}\": {\n      \"filter\": \".[] | select(.id == (\\$id|tonumber))\"\n    }\n  },\n  \"settings\": {\n    \"cli\": { \"options\": \"-c\" }\n  }\n}\nEOF\n```\n\nPlace the file in WORKDIR and execute it on the command line.\n\n``` sh\n$ : id\n$ docker run --rm -v $PWD:/app ghcr.io/kjdev/jq-api cli id -d id=1\n{\"id\":1,\"value\":\"first\"}\n$ : id/{id}\n$ docker run --rm -v $PWD:/app ghcr.io/kjdev/jq-api cli id/2\n{\"id\":2,\"value\":\"second\"}\n```\n\nPlace a file in WORKDIR to start the API server.\n\n``` sh\n$ docker run --rm --name app -d -p 80:80 -v $PWD:/app ghcr.io/kjdev/jq-api server\n```\n\nAccess the API server.\n\n``` sh\n$ : id\n$ curl -G localhost/id -d id=2\n{\"id\":2,\"value\":\"second\"}\n$ : id/{id}\n$ curl -G localhost/id/3\n{\"id\":3,\"value\":\"third\"}\n```\n\nStop the API server.\n\n``` sh\n$ docker stop app\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkjdev%2Fjq-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkjdev%2Fjq-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkjdev%2Fjq-api/lists"}