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 --watch
Generate the markdown API refrence
> rests ./api.js --docs
TikAPI is using Rests:
- [ ] 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)
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.
-
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
-
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}
.
- 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