Rests

Work with requests in a modern and beautiful way.

Easily generate API client's SDK — organize and simplify HTTP Requests.

An API Request with Rests✅

1api.login({
2	user: 'test',
3	password: 'test'
4})
5.then(({json})=>(
6	console.log(`Logged in!`)
7));

Normal API Request❌

1fetch("https://example.com/login",{
2   'method': 'POST',
3   'headers': {
4   	'Content-Type': 'application/x-www-form-urlencoded'
5   },
6   'data': `user=${user}&password=${password}`
7}).then((res) => (if(!res.ok){ return Promise.reject("error"))})
8.then((res) => res.json())
9.catch((err) => console.warn)
10.then(data)=> (console.log("Finally the response")));

Features

• One source of truth for all your API requests
• Robust configuration, makes it easier to handle validation, authentication, and hooks
• Complex inheritance, split requests into multiple categories/subcategories and prevent repetition
• Generate Typescript types for your API automatically
• Generate a simple markdown reference automatically
• Supports schema from pure JSON
• Universal support - works on Browsers & Node.js
• 🪐 Private edition only: Generate Python API with type hints
• 🪐 Private edition only: Generate Beautiful documenation website, with complete request and response examples, and OpenAPI schema definitions

& more

Installation

npm i rests

You should also install it globally in order to easily run the cli.

npm i rests -g

Import

Recommended

1import Rests from 'rests';

With CommonJS

Import it like this to get the Types & Intellisense suggestions on CommonJS

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

Usage

1import Rests from 'rests';
2
3const API = Rests({
4	$options: {
5		base: 'https://example.com'
6	},
7	user:{
8		login:{
9			path: '/user/login',
10			method: 'POST',
11			params:{
12				username:{
13					required: true,
14					type: "string",
15					help: "A valid username is required",
16					validate: /\w+/
17				},
18				password: {
19					required:  true,
20					help: "A valid password is required",
21					type: "string",
22					
23					format: (password) => { 
24						if(password.length < 8){
25							throw new Error("The password must be at least 8 characters.");
26						}
27						return password;
28					}
29
30				}
31			}
32		},
33		profile: {
34			$options:{
35				params:{
36					//Set authentication parameters for all requests in this category
37					authorization: {...} 
38				}
39			}
40			info: {
41				...
42			},
43			update: {
44				...
45			}
46		}
47	}
48});
49
50export default API;
51

Then you can call your API like this

1import API from './API.js';
2
3API.user.login({
4	username: 'nice',
5	password: 'mypassword'
6})
7.then((res)=>{
8	console.log(res.json);
9	//Successful Response, body automatically parsed.
10})
11.catch((res)=>{
12	console.log(res.json || res.message);
13	//Error Response 
14})

Example Validation error

1import API from './API.js';
2
3API.user.login({
4	username: 'john', 
5	password: 'short'
6}).catch((err) => {
7	console.log(err.field, err.message); 
8	//Prints: password The password must be at least 8 characters.
9});
10

Initialization and Setting Variables

A category is like a class instance, you can intialize it with new values/options.

You can set parameter values for all requests in a category scope

1const User = new api.user({
2	authorization: 'user_auth_token'
3}); 
4

You can also update the options for a category by using the special $options key

1const User = new api.user({
2	$options: {
3		on_error: (error)=>{
4			if(error?.statusCode == 401){
5				alert("Session has expired");
6			}
7		}
8	}
9}); 

CLI Usage

Rests comes with a simple CLI for generating types and API markdown reference.

Generate the types file ./api.d.ts automatically and watch for changes

1> rests ./api.js --types --watch

Generate the markdown API refrence

1> rests ./api.js --docs

Rests with automatic typings in action

Projects using Rests

TikAPI is using Rests:

• https://github.com/tikapi-io/tiktok-api

TODO

• Support cookie as parameter location
• Support raw body requests without parameters (e.g API.user(rawBodyBytes))
• Feature: Store cookie jar and persist session cookies over requests (same as python requests lbirary)

Schema Reference

Categories

An API category is an object consisting of Endpoint Objects or subcategories. A category can also contain these special keys:

• $options: Options for this category and it's subcategories, overriding other options. See Options
• help: A description of the category.

Endpoint Object

• path: The request path or full URL, which can also contain named parameters.
• method: The request method, GET,POST etc. (default: GET)
• enctype: The body encode type for *only for requests that have body parameters:
  • json (application/json) (default)
  • form (multipart/form-data)
  • urlencode (application/x-www-form-urlencoded)
• params: An object consisting of Params Objects.
• help: A description of this endpoint
• example_response: Example response used for documentation generation
• on_success: See Options
• on_error: See Options
• on_request: See Options
• $other: Any other custom option you may need to include

Params Object

• name: The parameter HTTP name, this defaults to the object key name.

• required: boolean (default: false).

• help: A helpful message to throw if the parameter is invalid.

• type: Supported types:

  • "string"
  • "number"
  • "array"
  • "object"
  • "boolean"
  • "any" (default)

• format: A function to format the parameter value, or throw an error if it's invalid.

• validate: Regex validation.

• default: A default value.

• location: The location where this parameter will be in the HTTP request fields:

  • body the param will be included in request body (default for POST request)
  • query the param will be URL encoded in request URL query (default for GET request)
  • headers the param will be included in request headers
  • path the param will be included in request path
    • Note: You must also declare the named parameter key in the Endpoint path like /get/{key}.

• example : Example values used for documentation generation

• in: Array of allowed values

• max: Maximum allowed value for number types

• min: Minimum allowed value for number types

Options

The options object can be defined in every category using the special $options key, all the subcatgories will inherit them.

Rested(endpoints, options?)

• base: This will be prepended before each requests path. (e.g https://example.com)

• sandboxBase: For sandbox requests.

• headers: Key-value object of headers to include in all requests

• params: Params to include in all requests

• values: Key-value object store to set default values for all parameters

• on_request: A global hook function that is called before each request. Accepts an object of {url, options, params, key, instance, self} where self is the current method function.

  To modify the request:

  1return {url, options}

  To prevent the request from sending:

  1return false

• on_success: A hook function that is called on successful response, you can also modify and return a different response. Accepts (response, request).

• on_error: A hook function that is called on errors. Accepts (error_response, request). You can also return a new error like this:

  1return Promise.reject(CustomErrorResponse)

• fetch_agent: You can use this option to configure proxy if you're using node-fetch.

• proxies: Requests proxies dict, for python version only.

• $other: Any other custom option you may need to include