rests
Version:
Easily generate API client's SDK — organize and simplify API Requests.
302 lines (235 loc) • 8.7 kB
Markdown
# 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✅
```javascript
api.login({
user: 'test',
password: 'test'
})
.then(({json})=>(
console.log(`Logged in!`)
));
```
### Normal API Request❌
```javascript
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")));
```
## 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 <img src='https://i.imgur.com/C6sVrY1.png' style='vertical-align:middle' /> 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
```javascript
import Rests from 'rests';
```
### With CommonJS
Import it like this to get the Types & Intellisense suggestions on CommonJS
```javascript
const Rests = require("rests").default;
```
## Usage
```javascript
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;
```
### Then you can call your API like this
```javascript
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
})
```
### Example Validation error
```javascript
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.
});
```
### 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
```javascript
const User = new api.user({
authorization: 'user_auth_token'
});
```
You can also update the options for a category by using the special `$options` key
```javascript
const User = new api.user({
$options: {
on_error: (error)=>{
if(error?.statusCode == 401){
alert("Session has expired");
}
}
}
});
```
## 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
```bash
> rests ./api.js --types --watch
```
Generate the markdown API refrence
```bash
> rests ./api.js --docs
```
## Rests with automatic typings in action
<img src='https://i.imgur.com/nQGSyaf.png'>
## Projects using Rests
[TikAPI](https://tikapi.io) 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 Object](#endpoint-object)s or subcategories.
A category can also contain these special keys:
- **`$options`**: Options for this category and it's subcategories, overriding other options. See [Options](#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 Object](#params-object)s.
- **`help`**: A description of this endpoint
- **`example_response`**: Example response used for documentation generation
- **`on_success`**: See [Options](#options)
- **`on_error`**: See [Options](#options)
- **`on_request`**: See [Options](#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:
```javascript
return {url, options}
```
To prevent the request from sending:
```javascript
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:
```javascript
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