Work with requests in a modern and beautiful way.
Easily generate API client's SDK — organize and simplify HTTP Requests.
api.login({
user: 'test',
password: 'test'
})
.then(({json})=>(
console.log(`Logged in!`)
));fetch("https://example.com/login",{
'method': 'POST',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
'data': `user=${user}&password=${password}`
}).then((res) => (if(!res.ok){ return Promise.reject("error"))})
.then((res) => res.json())
.catch((err) => console.warn)
.then(data)=> (console.log("Finally the response")));- 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
npm i rests
You should also install it globally in order to easily run the cli.
npm i rests -g
Recommended
import Rests from 'rests';Import it like this to get the Types & Intellisense suggestions on CommonJS
const Rests = require("rests").default;import Rests from 'rests';
const API = Rests({
$options: {
base: 'https://example.com'
},
user:{
login:{
path: '/user/login',
method: 'POST',
params:{
username:{
required: true,
type: "string",
help: "A valid username is required",
validate: /\w+/
},
password: {
required: true,
help: "A valid password is required",
type: "string",
format: (password) => {
if(password.length < 8){
throw new Error("The password must be at least 8 characters.");
}
return password;
}
}
}
},
profile: {
$options:{
params:{
//Set authentication parameters for all requests in this category
authorization: {...}
}
}
info: {
...
},
update: {
...
}
}
}
});
export default API;import API from './API.js';
API.user.login({
username: 'nice',
password: 'mypassword'
})
.then((res)=>{
console.log(res.json);
//Successful Response, body automatically parsed.
})
.catch((res)=>{
console.log(res.json || res.message);
//Error Response
})import API from './API.js';
API.user.login({
username: 'john',
password: 'short'
}).catch((err) => {
console.log(err.field, err.message);
//Prints: password The password must be at least 8 characters.
});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
const User = new api.user({
authorization: 'user_auth_token'
}); You can also update the options for a category by using the special $options key
const User = new api.user({
$options: {
on_error: (error)=>{
if(error?.statusCode == 401){
alert("Session has expired");
}
}
}
}); 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
> rests ./api.js --types --watchGenerate the markdown API refrence
> rests ./api.js --docs
TikAPI is using Rests:
- Support
cookieas 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)
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 Optionshelp: A description of the category.
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 endpointexample_response: Example response used for documentation generationon_success: See Optionson_error: See Optionson_request: See Options$other: Any other custom option you may need to include
-
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:bodythe param will be included in request body (default for POST request)querythe param will be URL encoded in request URL query (default for GET request)headersthe param will be included in request headerspaththe param will be included in request path- Note: You must also declare the named parameter key in the Endpoint path like
/get/{key}.
- Note: You must also declare the named parameter key in the Endpoint path like
-
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
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.ghttps://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:
return {url, options}
To prevent the request from sending:
return 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:return 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