Wrape
Easily generate API client's SDK — organize and simplify API Requests. If you find yourself repeating HTTP requests code blocks, then this library is for you.
Transform this
fetch("https://example.com/login",{
'method': 'POST',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
'data': 'user=test&password=test'
}).then((res) => (if(!res.ok){ throw new Error("error")})
.then((res) => res.json())
.catch((err) => console.warn)
.then(data)=> (console.log("Finally the response")));
Into this
api.login({
user: 'test',
password: 'test'
})
.then((data)=>(console.log(`Logged in!`)));
Features
- No dependencies, using Fetch API
- Documentation Generator
- Multiple API categories & subcategories
- Elegant parameter handling
- Universal support, small size (2.9KB)
- For Browsers & Node.js
Installation
npm i wrape
Usage
You start by writing a JSON schema of all your API endpoints. You can split requests into categories and subcategories.
import Wrape from 'wrape';
const endpoints = {
user:{
login:{
path: '/user/login',
method: 'POST',
params:{
username:{
required: true,
},
password: {
required: true,
help: "The password must be at least 8 characters.",
validate: (password) => { return password.length >= 8;}
}
}
}
}
}
const api = Wrape(api_config,{ base: 'https://example.com'});
api.user.login({username: 'john', password:'short'}).catch((err) => {
console.log(err.message); //The password must be at least 8 characters.
});
api.user.login({username: 'john', password:'wrong_password'})
.catch((res) => {
console.log(res.json.message); //User password is invalid.
console.log(res.status); //401
});
Real-life Usages
Some projects using Wrape:
Quick Documentaion
API Configuration
Categories
An API category is an object consisting of Endpoint Objects or subcategories. A category can also contain special keys:
-
$options
: Set options for this category, same object as Gloabl Options -
$help
: A description used for endpoint generation
Endpoint Object
-
method
: The request method ,GET,POST etc. -
path
: The request path or full URL, which can also contain named parameters, check exmaple below. -
enctype
: The body encode type for *only for requests that have body parameters:-
form
(multipart/form-data)
(default) -
url
(application/x-www-form-urlencoded)
-
json
(application/json)
-
text
(text/plain)
-
-
params
: An object consisting of Params Objects. -
response
: A hook function for modifying the response. -
request
: A hook function for modifying the request. -
help
: A description used for documantaion generation -
example_response
: Example response used for documentation generation
Params Object
-
name
: By default the param name is the Param object key. -
required
: If this param is required or not. -
format
: A function to format the parameter value. -
validate
: Validate the param values, it can be:- A Regular expression string.
- A function, that returns a boolean.
-
in
: Array of valid allowed values -
help
: An error message to throw if param is not valid, or required. -
default
: A default value for this param. -
location
: The location where this parameter will be in http request fields, it can be:-
body
the param will be encoded in body as form data (default for POST request) -
query
the param will be URL encoded in URL query (default for GET request) -
headers
the param will be set in request headers -
path
the param will be set in request path, you must declare the named parameters in path.
-
-
example
: Example values used for documentation generation
Global Options
This is the global options you set when you initalize Wrape, these options can be overridden by Category options.
Wrape(endpoints,global_options)
-
base
: The base Origin for all endpoints, will be prepended to each request path, default is empty. -
headers
: Append Headers to all requests -
values
: An object of{param_key : param_value}
, useful for setting default values for all categories and endpoints. -
sender
: Use a custom function to send request ->custom_fetch(url, options, wrape_options, response_middleware?)
-
request_middleware
: Global hook pre-request function -
response_middleware
: Global hook on response function -
fetch_parse
: Parse Fetch Response (await JSON body\await body text) (default true) -
fetch_error_handler
: Function to handle fetch errors -
fetch_agent
: You can use this option to set proxy if you're using node-fetch.
Documentation Generator
You can generate a Markdown reference of the API, just like this:
api.$docs({
output: "API.md",
});
Responses
The response of request is parsed based when fetch_parse
option is true, returning an object like this:
{
status: 200,
statusText: 'OK',
headers: {...},
json: {'message': 'success'},
}
Depending on the content type, you can get the body as text
or json
.
Advanced Example
In this example we declare a user category and set it's options with the special $options
key.
We also declare a information
endpoint which contains path
parameters.
import Wrape from 'wrape';
const endpoints = {
user:{
//This $options: A special key which overrides Global Options for this category and it's subcategories
$options:{
base: 'https://example.com/login'
},
profile:{
information:{
path: '/profile/:id',
method: 'GET',
params:{
id:{
required: true,
help: "The user ID is required.",
validate: "^[0-9]+$",
location: "path"
},
key:{
name: 'Authorization',
required: true,
help: "The user authorization token is required.",
validate: "^Bearer (.*?)$",
location: "headers"
}
}
},
edit: {...} //Other Endpoint/Subcategories for this category
}
}
}
const api = Wrape(api_config);
Setting Variables
You can set enviroment variables for a category by initializing it with set
function.
const User = new api.user.set({
authorization: 'default_auth_token'
});
User.info({id: 1}).then((res) => {
console.log(res.json);
});