Registry / http-networking / rests
library0.0.1jsnpmunverified

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.

npm install rests
INSTALL
IMPORT
SIG · RESTS
R
rests
http-networkingjavascriptv0.0.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Rests
✓ import Rests from 'rests';
✗ import { Rests } from 'rests';
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.
Rests (CommonJS)
✓ const Rests = require("rests").default;
✗ const Rests = require("rests");
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.
RestsAPISchema
✓ import type { RestsAPISchema } from 'rests';
✗ import { RestsAPISchema } from 'rests';
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.

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.

import Rests from 'rests'; // Define your API schema with endpoints, methods, and validation rules const APIBuilder = Rests({ $options: { base: 'https://api.example.com' // Set the base URL for all requests }, user: { login: { path: '/user/login', method: 'POST', params: { username: { required: true, type: "string", help: "A valid username is required", validate: /^[a-zA-Z0-9_]+$/ // Example validation for alphanumeric username }, password: { required: true, help: "A valid password is required", type: "string", format: (password: string) => { if (password.length < 8) { throw new Error("The password must be at least 8 characters."); } return password; } } } }, profile: { $options: { // Set authentication parameters for all requests in this category params: { authorization: { type: "string", required: true } } }, info: { path: '/user/profile/info', method: 'GET' }, update: { path: '/user/profile/update', method: 'POST', params: { email: { type: "string", format: (email: string) => email.toLowerCase() } } } } } }); // The API client is ready to use const API = APIBuilder; // Example 1: Successful login call API.user.login({ username: 'john.doe', password: 'supersecurepassword123' }) .then((res) => { console.log('Login successful, response body:', res.json); }) .catch((err) => { console.error('Login failed:', err.json || err.message); }); // Example 2: Calling an endpoint with a validation error API.user.login({ username: 'testuser', password: 'short' // This will trigger the password format validation error }) .catch((err) => { console.log('Validation Error:', err.field, err.message); // Expected output: "Validation Error: password The password must be at least 8 characters." }); // Example 3: Initializing a category with specific options (e.g., authorization) const UserAPI = new API.user({ authorization: 'my_user_auth_token_xyz' }); UserAPI.profile.info() .then((res) => console.log('User profile info retrieved:', res.json)) .catch((err) => console.error('Failed to get user profile:', err.message));
Debug
Known issues
gotchaWhen 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.
fix
Change `const Rests = require('rests');` to `const Rests = require('rests').default;`
affects: >=1.0.0
gotchaSpecific 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.
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.
affects: >=1.0.0
gotchaWhile `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.
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>`.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Rests is not a function
Attempting to call the `rests` module object directly when using CommonJS `require()`, instead of its default export.
fix
Ensure you are importing the default export: `const Rests = require('rests').default;`
The password must be at least 8 characters.
A request parameter failed a custom `format` or `validate` function defined in the API schema for that specific parameter.
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.
ReferenceError: API is not defined
The API client instance (`API` in examples) was not correctly initialized, exported, or imported before being used in the current scope.
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.
Error: Request failed with status code 401
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.
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.
Upgrade
Version history
0.0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
9 hits · last 30 days
node
8
Resources
rests — npm install rests · libregistry