{"id":13835,"library":"purest","title":"Purest REST API Client","description":"Purest is a flexible JavaScript library for constructing expressive REST API clients, abstracting away the low-level HTTP request details. It enables developers to define detailed API configurations, including base URLs, paths, headers, and versioning, for various service providers. The library then facilitates interaction through a fluent, chainable API that supports custom query parameters, authentication, and HTTP methods, with options for preconfigured defaults and method aliases. Currently in stable version 4.0.3, Purest is actively maintained, supporting Node.js environments (>=12.0.0) and ships with TypeScript types for improved developer experience. It relies on the `request-compose` library for its underlying HTTP capabilities. Purest differentiates itself by providing a highly configurable and declarative approach to API consumption, allowing for complex API structures to be represented and interacted with in an abstract yet powerful manner, making it suitable for managing interactions with multiple, diverse REST APIs within a single application.","status":"active","version":"4.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/simov/purest","tags":["javascript","rest","restful","api","http","https","client","typescript"],"install":[{"cmd":"npm install purest","lang":"bash","label":"npm"},{"cmd":"yarn add purest","lang":"bash","label":"yarn"},{"cmd":"pnpm add purest","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Purest is built on top of this powerful HTTP client for making requests.","package":"request-compose","optional":false}],"imports":[{"note":"The `purest` factory function is the default export. Use `require('purest')` for CommonJS.","wrong":"import { purest } from 'purest'","symbol":"purest","correct":"import purest from 'purest'"},{"note":"Import the `PurestClient` type for improved type-checking and IntelliSense when working with instantiated Purest clients.","symbol":"PurestClient","correct":"import type { PurestClient } from 'purest'"}],"quickstart":{"code":"import purest from 'purest';\n\nconst config = {\n  \"google\": {\n    \"default\": {\n      \"origin\": \"https://www.googleapis.com\",\n      \"path\": \"{path}\",\n      \"headers\": {\n        \"authorization\": \"Bearer {auth}\"\n      }\n    },\n    \"youtube\": {\n      \"origin\": \"https://www.googleapis.com\",\n      \"path\": \"youtube/{version}/{path}\",\n      \"version\": \"v3\",\n      \"headers\": {\n        \"authorization\": \"Bearer {auth}\"\n      }\n    }\n  }\n};\n\nasync function getYouTubeChannels(username: string, token: string) {\n  const google = purest({ provider: 'google', config });\n\n  try {\n    const { res, body } = await google('youtube')\n      .get('channels')\n      .qs({ forUsername: username })\n      .auth(token)\n      .request();\n\n    console.log('Status:', res.statusCode);\n    console.log('Body:', JSON.stringify(body, null, 2));\n    return body;\n  } catch (error) {\n    console.error('Error fetching YouTube channels:', error);\n    throw error;\n  }\n}\n\n// Example usage: replace with your actual Google API token and desired username\nconst GOOGLE_AUTH_TOKEN = process.env.GOOGLE_AUTH_TOKEN ?? 'YOUR_GOOGLE_AUTH_TOKEN';\nconst TARGET_USERNAME = 'GitHub'; \n\nif (GOOGLE_AUTH_TOKEN === 'YOUR_GOOGLE_AUTH_TOKEN') {\n    console.warn(\"Please set GOOGLE_AUTH_TOKEN environment variable or replace 'YOUR_GOOGLE_AUTH_TOKEN' with an actual token to run this example.\");\n} else {\n    getYouTubeChannels(TARGET_USERNAME, GOOGLE_AUTH_TOKEN)\n        .then(() => console.log(`Attempted to fetch YouTube channels for ${TARGET_USERNAME}.`))\n        .catch(() => console.error('Failed to execute YouTube channel fetch example.'));\n}","lang":"typescript","description":"This example demonstrates how to configure a Purest client for Google's YouTube API, apply an authentication token, query for channels by username, and execute the request."},"warnings":[{"fix":"Always consult the official migration guides provided in the GitHub repository or npm documentation when upgrading Purest across major versions to understand necessary configuration and code changes.","message":"Major version upgrades (e.g., v2 to v3, or v3 to v4) introduce breaking changes to the API configuration format, method signatures, or internal behavior. Direct upgrades between major versions without code adjustments are generally not supported.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure all Purest method chains are terminated with a call to `.request()` (e.g., `purestClient.get('path').auth(token).request()`) to execute the API call.","message":"Forgetting to call `.request()` at the end of a method chain will not dispatch the HTTP request. The chain merely builds the request definition until `.request()` is explicitly called.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Carefully verify the structure and token placement within your `config` object for each provider. Ensure that `auth()` calls match the `{auth}` token in your headers configuration, and `{path}` and `{version}` tokens are correctly used in URL paths.","message":"The configuration object for API providers can be complex, especially with dynamic tokens like `{path}`, `{version}`, and `{auth}`. Incorrectly defined origins, paths, or headers will lead to malformed URLs or failed authentication.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use the default import syntax: `import purest from 'purest';` for ESM, or `const purest = require('purest');` for CommonJS.","message":"When using TypeScript or modern JavaScript with ESM, attempting to import `purest` as a named export (`import { purest } from 'purest'`) will result in a runtime error because `purest` is a default export.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'12.0.0':84 '4.0.3':76 'abstract':17,134 'activ':79 'alias':71 'allow':121 'api':3,15,32,54,119,124,148,156 'applic':152 'approach':117 'authent':60 'away':18 'base':35 'capabl':106 'chainabl':53 'client':4,16,159 'complex':123 'compos':100 'configur':33,114 'construct':12 'consumpt':120 'current':72 'custom':57 'declar':116 'default':68 'defin':30 'detail':25,31 'develop':28,92 'differenti':108 'divers':146 'enabl':27 'environ':83 'experi':93 'express':13 'facilit':48 'flexibl':8 'fluent':52 'header':38 'high':113 'http':23,62,105,157 'https':158 'improv':91 'includ':34 'interact':49,130,143 'javascript':9,153 'level':22 'librari':10,46,101 'low':21 'low-level':20 'maintain':80 'make':138 'manag':142 'manner':137 'method':63,70 'multipl':145 'node.js':82 'option':65 'paramet':59 'path':37 'power':136 'preconfigur':67 'provid':44,111 'purest':1,5,77,107 'queri':58 'reli':95 'repres':128 'request':24,99 'request-compos':98 'rest':2,14,147,154,155 'servic':43 'ship':86 'singl':151 'stabl':74 'structur':125 'suitabl':140 'support':56,81 'type':89 'typescript':88,160 'under':104 'url':36 'various':42 'version':40,75 'within':149 'yet':135","created_at":"2026-04-20T01:56:33.329926+00:00","updated_at":"2026-04-20T01:56:33.329926+00:00","problems":[{"fix":"Change your import statement from `import { purest } from 'purest';` to `import purest from 'purest';`.","cause":"This typically occurs when using an incorrect import statement for Purest, treating its default export as a named export.","error":"TypeError: purest is not a function"},{"fix":"Verify that your `purest({provider: 'your-provider', config})` call is correctly configured and successfully returns a client object before attempting to chain methods or call `.request()`.","cause":"This error indicates that the object you are trying to call `.request()` on is undefined. This often happens if the `purest()` call itself failed to return a valid client instance, possibly due to missing or invalid provider configuration.","error":"TypeError: Cannot read properties of undefined (reading 'request')"},{"fix":"Ensure your `config` object includes a correctly structured entry for the provider name you are trying to initialize (e.g., `config = { 'google': { ... } }`).","cause":"The `config` object passed to `purest` either does not contain a definition for the specified `provider` name, or the configuration for that provider is malformed or empty.","error":"Error: Missing provider configuration for 'your-provider'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.0.2","cli_name":"","cli_version":null,"type":"library","homepage":"https://simov.github.io/purest/","github":"https://github.com/simov/purest","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/purest","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}