{"id":16197,"library":"rests","title":"Rests API Client SDK Generator","description":"Rests is a JavaScript/TypeScript library designed to streamline and centralize HTTP API requests by enabling the generation of a structured API client SDK. It empowers developers to define API endpoints, methods, and parameters in a declarative, JSON-like configuration, thereby establishing a single source of truth for all API interactions. Key features include a robust configuration system that facilitates advanced handling of validation, authentication, and request/response hooks, alongside a powerful mechanism for complex inheritance that allows for the categorization of requests to prevent repetition. A significant differentiator is its capability to automatically generate TypeScript types for the defined API, enhancing developer experience and ensuring type safety. Additionally, it supports schema definition from pure JSON and can generate basic markdown API references. Rests offers universal compatibility, functioning seamlessly across both browser and Node.js environments. The current stable version is 1.1.1. While a specific release cadence is not explicitly detailed, the project appears to be under active development, evidenced by mentions of a 'Private edition' offering expanded functionalities. Its primary distinction lies in transforming a simple, declarative API definition into a fully-fledged, strongly-typed, and object-oriented API client, significantly simplifying network communication compared to direct `fetch` or `axios` implementations.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/el1s7/rests","tags":["javascript","sdk","api","client","generate","openapi","swagger","wrape","rest","typescript"],"install":[{"cmd":"npm install rests","lang":"bash","label":"npm"},{"cmd":"yarn add rests","lang":"bash","label":"yarn"},{"cmd":"pnpm add rests","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the recommended ES Module import for the Rests factory function, which serves as the primary entry point for defining and creating your API client instance.","wrong":"import { Rests } from 'rests';","symbol":"Rests","correct":"import Rests from 'rests';"},{"note":"For CommonJS environments, explicitly access the `.default` property of the module export to correctly import the Rests factory function and ensure proper TypeScript type inference and Intellisense.","wrong":"const Rests = require(\"rests\");","symbol":"Rests (CommonJS)","correct":"const Rests = require(\"rests\").default;"},{"note":"Used for TypeScript type-checking the configuration object passed to the `Rests` factory function when defining your API schema. The exact name of the schema type may vary based on library exports, but `RestsAPISchema` is a common pattern.","wrong":"import { RestsAPISchema } from 'rests';","symbol":"RestsAPISchema","correct":"import type { RestsAPISchema } from 'rests';"}],"quickstart":{"code":"import Rests from 'rests';\n\n// Define your API schema with endpoints, methods, and validation rules\nconst APIBuilder = Rests({\n  $options: {\n    base: 'https://api.example.com' // Set the base URL for all requests\n  },\n  user: {\n    login: {\n      path: '/user/login',\n      method: 'POST',\n      params: {\n        username: {\n          required: true,\n          type: \"string\",\n          help: \"A valid username is required\",\n          validate: /^[a-zA-Z0-9_]+$/ // Example validation for alphanumeric username\n        },\n        password: {\n          required: true,\n          help: \"A valid password is required\",\n          type: \"string\",\n          format: (password: string) => {\n            if (password.length < 8) {\n              throw new Error(\"The password must be at least 8 characters.\");\n            }\n            return password;\n          }\n        }\n      }\n    },\n    profile: {\n      $options: {\n        // Set authentication parameters for all requests in this category\n        params: {\n          authorization: { type: \"string\", required: true } \n        }\n      },\n      info: {\n        path: '/user/profile/info',\n        method: 'GET'\n      },\n      update: {\n        path: '/user/profile/update',\n        method: 'POST',\n        params: {\n          email: { type: \"string\", format: (email: string) => email.toLowerCase() }\n        }\n      }\n    }\n  }\n});\n\n// The API client is ready to use\nconst API = APIBuilder;\n\n// Example 1: Successful login call\nAPI.user.login({\n    username: 'john.doe',\n    password: 'supersecurepassword123'\n})\n.then((res) => {\n    console.log('Login successful, response body:', res.json);\n})\n.catch((err) => {\n    console.error('Login failed:', err.json || err.message);\n});\n\n// Example 2: Calling an endpoint with a validation error\nAPI.user.login({\n    username: 'testuser',\n    password: 'short' // This will trigger the password format validation error\n})\n.catch((err) => {\n    console.log('Validation Error:', err.field, err.message);\n    // Expected output: \"Validation Error: password The password must be at least 8 characters.\"\n});\n\n// Example 3: Initializing a category with specific options (e.g., authorization)\nconst UserAPI = new API.user({\n  authorization: 'my_user_auth_token_xyz'\n});\n\nUserAPI.profile.info()\n  .then((res) => console.log('User profile info retrieved:', res.json))\n  .catch((err) => console.error('Failed to get user profile:', err.message));","lang":"typescript","description":"Demonstrates how to define an API schema using the `Rests` factory, initialize the client, make successful and error-prone API calls, handle custom parameter validation, and set category-specific options like authorization."},"warnings":[{"fix":"Change `const Rests = require('rests');` to `const Rests = require('rests').default;`","message":"When using CommonJS (`require`), you must explicitly access the `.default` property of the module export to correctly import the Rests factory function. Failing to do so will result in `TypeError: Rests is not a function` or similar issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review the official Rests documentation to understand the feature set available in the public npm package. Contact the Rests maintainers for details regarding the 'Private edition' if those features are required.","message":"Specific advanced features, such as Python API generation with type hints and the creation of comprehensive documentation websites, are explicitly marked as 'Private edition only' and are not included in the public npm package. Users should not expect these functionalities out-of-the-box.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install the package globally using `npm i rests -g` if you intend to use its CLI directly, or execute CLI commands via `npx rests <command>`.","message":"While `rests` can be installed as a local dependency for project-level usage, its command-line interface (CLI) for generating types and documentation requires a global installation (`npm i rests -g`) or invocation via `npx`. Forgetting to install globally is a common reason for CLI commands failing.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are importing the default export: `const Rests = require('rests').default;`","cause":"Attempting to call the `rests` module object directly when using CommonJS `require()`, instead of its default export.","error":"TypeError: Rests is not a function"},{"fix":"Ensure all required parameters meet the specified validation and formatting rules before making the API call. Refer to the API schema definition for the specific endpoint.","cause":"A request parameter failed a custom `format` or `validate` function defined in the API schema for that specific parameter.","error":"The password must be at least 8 characters."},{"fix":"Verify that `const API = Rests({...});` has been executed and the `API` object is properly exported from its definition file and imported where it's being used.","cause":"The API client instance (`API` in examples) was not correctly initialized, exported, or imported before being used in the current scope.","error":"ReferenceError: API is not defined"},{"fix":"Implement proper error handling with a `.catch()` block on your API calls. Inspect `err.statusCode`, `err.json`, or `err.message` for details. Ensure authentication tokens are correctly set, potentially through category `$options` or when initializing a specific API category.","cause":"The API request received an HTTP error response, commonly due to missing or invalid authentication credentials (e.g., an expired token) or other server-side issues.","error":"Error: Request failed with status code 401"}],"ecosystem":"npm"}