{"id":26716617,"url":"https://github.com/javascript-studio/studio-json-request","last_synced_at":"2025-04-14T01:40:22.296Z","repository":{"id":24494237,"uuid":"67734524","full_name":"javascript-studio/studio-json-request","owner":"javascript-studio","description":"📡 A tiny Node HTTP(S) request wrapper for JSON APIs","archived":false,"fork":false,"pushed_at":"2024-01-30T16:30:42.000Z","size":437,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-27T15:51:55.368Z","etag":null,"topics":["http-client","json","timeout","validation"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/javascript-studio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-08T19:38:32.000Z","updated_at":"2022-04-10T13:45:36.000Z","dependencies_parsed_at":"2024-01-30T18:08:57.392Z","dependency_job_id":null,"html_url":"https://github.com/javascript-studio/studio-json-request","commit_stats":{"total_commits":79,"total_committers":2,"mean_commits":39.5,"dds":0.03797468354430378,"last_synced_commit":"00242c823a9aaef0cd1e1ac4f5e24842cf94cc23"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javascript-studio%2Fstudio-json-request","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javascript-studio%2Fstudio-json-request/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javascript-studio%2Fstudio-json-request/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/javascript-studio%2Fstudio-json-request/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/javascript-studio","download_url":"https://codeload.github.com/javascript-studio/studio-json-request/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248809038,"owners_count":21164893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["http-client","json","timeout","validation"],"created_at":"2025-03-27T15:38:05.437Z","updated_at":"2025-04-14T01:40:22.276Z","avatar_url":"https://github.com/javascript-studio.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Studio JSON Request\n\n📡 A tiny Node HTTP(S) request wrapper for JSON APIs.\n\n- Transparent JSON request / response handling\n- Timeout support\n- Status code validation and default validation for 2xx responses\n- Follows redirects, but only once\n- Unified error handling with status codes\n- Consistent logging with [Studio Log][4]\n\n## Usage\n\n```js\nconst request = require('@studio/json-request');\n\nrequest({\n  method: 'POST',\n  hostname: 'some-host',\n  path: '/some-path',\n  timeout: 5000\n}, { some: 'payload' }, (err, data, res) =\u003e {\n  // ...\n});\n```\n\n## API\n\n- `request(options[, data], callback)`: Creates a new HTTPS request, passing\n  the `options` to Node [http.request][1], except for these properties:\n    - `protocol`: The protocol to use. Must be either `\"http:\"` or `\"https:\"`.\n      Defaults to `\"https:\"`.\n    - `timeout`: The number of milliseconds after which the request should time\n      out, causing en `E_TIMEOUT` error.\n    - `expect`: The expected status code(s). This can be a number or an array\n      of numbers.\n    - `stream`: If `true`, the `callback` is invoked with `(null, res)` once\n      the header was retrieved to allow to stream the response.\n    - `log`: A [parent logger][4] to use for the \"Request\" logger.\n\n### Behavior\n\n- If the `timeout` option is specified, a timer is installed which will abort\n  the request and invoke the callback with an error.\n- If the `expect` option is specified, it validates the response HTTP status\n  code. If it's a number the status code has to equal that number. If an array\n  is given, any number in the array is accepted. If the option is not given,\n  the request will fail for non `2xx` status codes.\n- If the `stream` option is specified, the response is returned immediately\n  after the status code was checked. No further response processing is done by\n  this library. It is the callers responsibility to consume the response.\n- If `data` is given, it is stringified and passed as the request body and the\n  request is sent. The `Content-Type` header is set to `application/json`,\n  unless this header was already provided. The `Content-Length` is set to the\n  request body length.\n- If `data` is set to `null`, the request is sent without a body.\n- If `data` is omitted, the request object is returned and it's the callers\n  responsibility to invoke `req.end()` to complete the request.\n\n### Callback\n\nThe callback is invoked with `(err, data, response)`.\n\n- `err`: An error object or `null`. The error will have a `code` property with\n  these possible string values:\n    - `E_TIMEOUT`: The request timed out.\n    - `E_EXPECT`: The response status code does not match the expectation. The\n      `statusCode` property on the error object is set to the response status\n      code.\n    - `E_JSON`: Could not parse the response body as JSON. In this case `data`\n      is the raw body.\n    - `E_ERROR`: If an `error` event was thrown.\n- `data`: The parsed response data, or if it could not be parsed the raw body.\n- `response`: The response object.\n\n### Logging\n\nEvery request produces a log entry when the response was processed with this\ndata:\n\n- `request`:\n    - `protocol`: The protocol used\n    - `method`: The request method used\n    - `host`: The host name\n    - `path`: The path\n    - `headers`: The request headers, if any\n    - `port`: The port, if specified\n    - `body`: The request body, if given\n- `response`:\n    - `statusCode`: The response status code\n    - `headers`: The response headers\n    - `body`: The response body, if available\n- `ms_head`: The time it took to receive the response header\n- `ms_body`: The time it took to receive the response body\n\nIf `stream` was set, the log entry is produced once the response header was\nreceived without the `response` and `ms_body` properties, and another log entry\nis produced when the response body was received with `ms_body`.\n\nTo remove confidential information from the logs, you can use [Studio Log X][5].\nFor example, you can X-out all Authorization headers from the logs like this:\n\n```js\nconst logger = require('@studio/log');\nconst Console = require('@studio/log-format/console');\nconst logX = require('@studio/log-x');\n\n// Install filter on namespace \"Request\":\nlogger\n  .pipe(logX('request.headers.Authorization'))\n  .pipe(new Console());\n```\n\n## Related modules\n\n- 🎮 [Studio CLI][2] this module was initially developed for the [JavaScript\n  Studio][3] command line tool.\n- 👻 [Studio Log][4] is used for logging.\n- ❎ [Studio Log X][5] can be use to X-out confidential information from the\n  logs.\n- 📦 [Studio Changes][6] is used to create the changelog for this module.\n\n## License\n\nMIT\n\n\u003cdiv align=\"center\"\u003eMade with ❤️ on 🌍\u003c/div\u003e\n\n[1]: https://nodejs.org/dist/latest-v6.x/docs/api/http.html#http_http_request_options_callback\n[2]: https://github.com/javascript-studio/studio-cli\n[3]: https://javascript.studio\n[4]: https://github.com/javascript-studio/studio-log\n[5]: https://github.com/javascript-studio/studio-log-x\n[6]: https://github.com/javascript-studio/studio-changes\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjavascript-studio%2Fstudio-json-request","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjavascript-studio%2Fstudio-json-request","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjavascript-studio%2Fstudio-json-request/lists"}