{"id":14425,"library":"api-res","title":"API Res: Node.js HTTP(S) Request Library","description":"API Res is a lightweight Node.js HTTP(S) request library specifically designed for interacting with Nodal API services. Currently at version 1.0.3, it provides a simple interface for making RESTful API calls within a Node.js environment. While the exact release cadence is not specified, its minimalistic design suggests a focus on stability rather than frequent feature additions. Key differentiators include its explicit integration with Nodal APIs and a straightforward request syntax, aiming for ease of use in projects that leverage the Nodal framework. It serves as a foundational utility for consuming APIs, particularly those built with Nodal, by abstracting standard HTTP request complexities.","status":"maintenance","version":"1.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/keithwhor/api-res","tags":["javascript","API","Nodal","Node.js","Resource","HTTP","REST"],"install":[{"cmd":"npm install api-res","lang":"bash","label":"npm"},{"cmd":"yarn add api-res","lang":"bash","label":"yarn"},{"cmd":"pnpm add api-res","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Mentioned as a complementary tool; 'plays well with'. Not a direct runtime dependency but often used together.","package":"cmnd","optional":true}],"imports":[{"note":"Primarily designed for CommonJS environments in Node.js. Direct ESM import might not be supported without transpilation or a wrapper.","wrong":"import apiRes from 'api-res';","symbol":"apiRes","correct":"const apiRes = require('api-res');"},{"note":"If the library exposes specific methods directly on its module export, this CJS destructuring is common. ESM destructuring is unlikely without explicit support.","wrong":"import { get } from 'api-res';","symbol":"get","correct":"const { get } = require('api-res');"},{"note":"Similar to 'get', assuming direct method exports for convenience in CJS. Always prefer the main module import if methods aren't directly exported.","wrong":"import { post } from 'api-res';","symbol":"post","correct":"const { post } = require('api-res');"}],"quickstart":{"code":"const apiRes = require('api-res');\n\nasync function fetchData() {\n  try {\n    // Example GET request\n    const getResponse = await apiRes.get('http://localhost:3000/api/users');\n    console.log('GET Response Body:', getResponse.body);\n    console.log('GET Status Code:', getResponse.statusCode);\n\n    // Example POST request with data and headers\n    const payload = { name: 'Alice', email: 'alice@example.com' };\n    const postOptions = {\n      headers: {\n        'Content-Type': 'application/json',\n        'Authorization': `Bearer ${process.env.API_KEY ?? ''}` // Use env var for sensitive data\n      },\n      json: true // Instructs library to send and expect JSON\n    };\n    const postResponse = await apiRes.post('http://localhost:3000/api/users', payload, postOptions);\n    console.log('POST Response Body:', postResponse.body);\n    console.log('POST Status Code:', postResponse.statusCode);\n\n  } catch (error) {\n    console.error('An error occurred during API request:', error.message);\n    if (error.response) {\n      console.error('Error Response Body:', error.response.body);\n      console.error('Error Status Code:', error.response.statusCode);\n    }\n  }\n}\n\nfetchData();","lang":"javascript","description":"Demonstrates basic GET and POST requests, including sending JSON payloads, custom headers, and robust error handling for API responses."},"warnings":[{"fix":"Use `const apiRes = require('api-res');` for importing the library in Node.js applications.","message":"The library appears to be focused on CommonJS. Using 'import' syntax (ESM) directly may lead to runtime errors or require bundlers/transpilers to resolve.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Regularly review dependencies for known vulnerabilities and consider wrapping critical network calls with circuit breakers or retry mechanisms.","message":"As a relatively lightweight and possibly less actively maintained library (last update appears to be around v1.0.x), ensure it's compatible with your current Node.js version and that any security concerns in underlying HTTP modules are mitigated if used in production.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Inspect `error.message`, `error.code`, and potentially `error.response` properties within catch blocks to differentiate and handle errors gracefully, as shown in the quickstart example.","message":"Error handling for network issues (e.g., DNS resolution failure, connection timeout) versus application-level API errors (e.g., 404, 500) might require careful inspection of the `error` object structure returned by `api-res`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your project is configured for CommonJS modules (e.g., no `\"type\": \"module\"` in `package.json` or rename `.js` files to `.mjs` for ESM). For `api-res`, stick to `require()`.","cause":"Attempting to `require()` an ESM-only module, or using `import` syntax for a CJS-only module.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/api-res/index.js from /your/app.js not supported."},{"fix":"Always use `try...catch` blocks with `async/await` or `.catch()` with Promises to handle potential errors gracefully. Check if `error.response` exists before accessing its properties.","cause":"An asynchronous request failed, but the promise rejection was not caught, or the `response` object was null/undefined due to an unhandled network error.","error":"(node:XXXXX) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'body' of undefined"},{"fix":"Verify the API server is online, listening on the correct port, and that there are no firewall rules blocking the connection.","cause":"The target API server is not running or is not accessible at the specified address and port.","error":"Error: connect ECONNREFUSED 127.0.0.1:3000"}],"ecosystem":"npm"}