Rests API Client SDK Generator

Common errors

• TypeError: Rests is not a function

  cause 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.

  cause 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

  cause 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

  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.
  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.

Warnings

• gotcha 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.
  Fix: Change `const Rests = require('rests');` to `const Rests = require('rests').default;`
• gotcha 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.
  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.
• gotcha 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.
  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>`.

Install

• npm install rests npm
• yarn add rests yarn
• pnpm add rests pnpm

Imports

• Rests
  wrong:

  import { Rests } from 'rests';

  correct:

  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)
  wrong:

  const Rests = require("rests");

  correct:

  const Rests = require("rests").default;

  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
  wrong:

  import { RestsAPISchema } from 'rests';

  correct:

  import type { 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.

Quickstart

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));