{"id":17168,"library":"azure-iot-http-base","title":"Azure IoT HTTP Base Library","description":"The `azure-iot-http-base` package is an internal library within the Azure IoT Node.js SDKs, providing foundational HTTP-specific components and utilities. It is not intended for direct consumption by most application developers; instead, its functionalities are integrated and exposed through higher-level SDK packages such as `azure-iot-device-http` for device clients and `azure-iothub` for service clients. The current stable version is 1.12.3, released as part of the broader Azure SDKs for Node.js update cadence, which typically occurs every few months. Key differentiators include its specialized focus on HTTP operations within the Azure IoT ecosystem, its role as a low-level transport primitive, and its inclusion of TypeScript type definitions, ensuring robust development practices. It abstracts away the complexities of HTTP communication for IoT-specific scenarios, supporting Node.js versions 14.0.0 and above. Developers should generally rely on the orchestrating device or service SDKs for HTTP-based interactions, as this package handles the underlying mechanics.","status":"active","version":"1.12.3","language":"javascript","source_language":"en","source_url":"https://github.com/Azure/azure-iot-sdk-node","tags":["javascript","typescript"],"install":[{"cmd":"npm install azure-iot-http-base","lang":"bash","label":"npm"},{"cmd":"yarn add azure-iot-http-base","lang":"bash","label":"yarn"},{"cmd":"pnpm add azure-iot-http-base","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides core authentication primitives used by the HTTP components.","package":"@azure/core-auth","optional":false}],"imports":[{"note":"While exportable, direct usage of HttpsClient is generally discouraged. Most applications should use higher-level Azure IoT SDKs like azure-iot-device-http or azure-iothub which abstract transport details.","symbol":"HttpsClient","correct":"import { HttpsClient } from 'azure-iot-http-base'"},{"note":"Similar to HttpsClient, direct import is not common. This class provides the base HTTP client functionality within the internal SDK architecture.","symbol":"HttpClient","correct":"import { HttpClient } from 'azure-iot-http-base'"},{"note":"Defines the structure for HTTP request options used internally. Typically consumed when working directly with HttpClient or HttpsClient, which is rare for end-user applications.","symbol":"RequestOptions","correct":"import { RequestOptions } from 'azure-iot-http-base'"},{"note":"Provides authentication logic for Shared Access Keys, primarily used internally by the HTTP clients for establishing secure connections.","symbol":"SharedAccessKeyAuthenticationProvider","correct":"import { SharedAccessKeyAuthenticationProvider } from 'azure-iot-http-base'"}],"quickstart":{"code":"import { HttpsClient, RequestOptions, RequestAndResponse } from 'azure-iot-http-base';\nimport { URL } from 'url';\n\n// WARNING: This package is an internal library and direct usage is generally discouraged.\n// Most developers should use higher-level Azure IoT SDKs like 'azure-iot-device-http'\n// or 'azure-iothub' which manage these transport details.\n\nasync function makeSimpleHttpRequest() {\n  console.log('Attempting a low-level HTTP GET request using azure-iot-http-base (for demonstration purposes only)...');\n\n  const client = new HttpsClient();\n  const url = new URL('https://httpbin.org/get?source=azure-iot-http-base-demo');\n\n  const requestOptions: RequestOptions = {\n    method: 'GET',\n    url: url.toString(),\n    headers: { 'User-Agent': 'Azure-IoT-HTTP-Base-Demo/1.0' }\n  };\n\n  try {\n    const response: RequestAndResponse = await client.sendRequest(requestOptions);\n    console.log(`\\nHTTP Status: ${response.statusCode}`);\n    console.log(`Response Headers: ${JSON.stringify(response.headers, null, 2)}`);\n    console.log(`Response Body (truncated): ${response.body?.toString().substring(0, 200)}...`);\n  } catch (error: any) {\n    console.error(`\\nError making HTTP request: ${error.message}`);\n    if (error.response) {\n      console.error(`Status: ${error.response.statusCode}`);\n      console.error(`Body: ${error.response.body?.toString()}`);\n    }\n  }\n}\n\nmakeSimpleHttpRequest().catch(console.error);\n","lang":"typescript","description":"Demonstrates how to instantiate and use `HttpsClient` for a basic GET request, highlighting that this is an internal library not typically for direct consumption by end-user applications."},"warnings":[{"fix":"Always prefer using the official Azure IoT Device or Service SDKs for your application logic. Only interact with this package if you are extending the SDKs themselves or require very low-level HTTP transport control, which is rare.","message":"This package is an internal library and is NOT intended for direct public consumption. Developers should use higher-level Azure IoT SDKs (e.g., `azure-iot-device-http`, `azure-iothub`) which abstract and manage these HTTP components.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js runtime to version 14.0.0 or higher. Node.js 12 reached end-of-life in April 2022.","message":"The minimum required Node.js version was updated from Node.js 12 to Node.js 14. Applications running on older Node.js versions will encounter runtime errors.","severity":"breaking","affected_versions":">=1.12.0"},{"fix":"No direct action required for most users, as this is an internal SDK change. If you were directly referencing internal types or structures related to `@azure/core-http` from this package (which is discouraged), be aware of potential interface changes or dependency mismatches.","message":"The internal dependency for core HTTP authentication shifted from `@azure/core-http` to `@azure/core-auth` starting from version 1.12.2. While this is primarily an internal change, it signifies a restructuring in how authentication and HTTP client pipelines are managed within the SDK.","severity":"breaking","affected_versions":">=1.12.2"},{"fix":"Regularly update `azure-iot-http-base` and other Azure SDK packages to their latest versions to receive critical security fixes and performance improvements.","message":"Recurring dependency vulnerabilities are addressed across releases. While patched regularly, it highlights the importance of keeping Azure SDKs updated to mitigate potential security risks.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure that any URL arguments are converted to strings using `url.toString()` before passing them to internal client methods, for example: `url: myUrl.toString()`.","cause":"Attempting to pass a `URL` object directly to a method expecting a string URL within an older version or specific internal client implementation that hasn't fully adopted `URL` objects.","error":"Error: The 'url' argument must be of type string. Received an instance of URL"},{"fix":"Implement robust error handling around network requests, checking for the existence of `error.response` and its properties before accessing them. For example, `if (error.response) { console.error(error.response.statusCode); }`.","cause":"Occurs when a low-level network request fails catastrophically or encounters an unexpected error state, leading to a `response` object being `undefined` or incomplete within the error object.","error":"TypeError: Cannot read properties of undefined (reading 'statusCode') when handling response."},{"fix":"Ensure your Node.js project is configured for ES Modules (`\"type\": \"module\"` in `package.json`) and use `import` statements. If using CommonJS, ensure you are using a compatible Node.js version and correct `require()` syntax (though `require` is generally not recommended for modern Azure SDKs).","cause":"While the package is designed for Node.js 14+ and ships TypeScript types, an outdated build configuration or incorrect usage (e.g., trying to `require()` in an ES Module context) might lead to module resolution issues.","error":"Error: This package has a 'main' entrypoint that is not compatible with ES Modules."}],"ecosystem":"npm","meta_description":null}