README
Purest
REST API Client Library
var purest = require('purest')
var google = purest({provider: 'google'})
await google
.query('youtube')
.select('channels')
.where({forUsername: 'GitHub'})
.auth(token)
.request()
Table of Contents
This is Purest v4, for older releases take a look at v3 and v2
Introduction
Purest is a tool for creating expressive REST API clients
Default Endpoint
Here is a basic configuration for Google:
{
"google": {
"default": {
"origin": "https://www.googleapis.com",
"path": "{path}",
"headers": {
"authorization": "Bearer {auth}"
}
}
}
}
With it we can instantiate that provider:
var google = purest({provider: 'google', config})
Then we can request some data from YouTube:
var {res, body} = await google
.get('youtube/v3/channels')
.qs({forUsername: 'GitHub'})
.auth(token)
.request()
Explicit Endpoint
We can define explicit endpoint for accessing YouTube:
{
"google": {
"default": {
"origin": "https://www.googleapis.com",
"path": "{path}",
"headers": {
"authorization": "Bearer {auth}"
}
},
"youtube": {
"origin": "https://www.googleapis.com",
"path": "youtube/{version}/{path}",
"version": "v3",
"headers": {
"authorization": "Bearer {auth}"
}
}
}
}
Then request the same data from YouTube:
var {res, body} = await google('youtube')
.get('channels')
.qs({forUsername: 'GitHub'})
.auth(token)
.request()
Defaults
Every method in Purest can also be passed as an option:
var google = purest({provider: 'google', config,
defaults: {auth: token}
})
Then we no longer need to set the access token for every request:
var {res, body} = await google('youtube')
.get('channels')
.qs({forUsername: 'GitHub'})
.request()
Method Aliases
But what if we want to make our API more expressive? What if we want to make it our own:
var google = purest({provider: 'google', config,
defaults: {auth: token},
methods: {get: ['select'], qs: ['where']}
})
Yes we can:
var {res, body} = await google('youtube')
.select('channels')
.where({forUsername: 'GitHub'})
.request()
Purest Options
Purest is a flexible tool for abstracting out REST APIs
var google = purest({config: {}, provider: 'google', defaults: {}, methods: {}})
Key | Type | Description
:-| :-: | :-
config
| {}
| Provider configuration to use
provider
| ''
| Provider name to initialize from the list of providers found in config
defaults
| {}
| Any supported configuration option set by default, see below
methods
| {}
| List of methods and their aliases to use with this instance
Request Options
Purest is built on top of a powerful HTTP Client
URL Options
Option | Description
:- | :-
origin
| The protocol and domain part of the URL, can contain {subdomain}
token
path
| The path part of the URL, can contain {version}
, {path}
and {type}
tokens
subdomain
| Subdomain part of the URL to replace in origin
version
| Version string to replace in path
type
| Type string to replace in path
, typically json
or xml
HTTP Methods
All HTTP methods get
head
post
put
patch
options
delete
trace
connect
accept a string to replace the {path}
configuration token with, or absolute URL to replace the entire url
.
Request Options
Option | Type | Description |
---|---|---|
method |
'string' |
Request method, implicitly set if one of the above HTTP Methods is used |
url |
'string' url object |
Absolute URL, automatically constructed if the URL Options above are being used, or absolute URL is passed to any of the HTTP Methods above |
proxy |
'string' url object |
Proxy URL; for HTTPS you have to use tunneling agent instead |
qs |
{object} 'string' |
URL querystring |
headers |
{object} |
Request headers |
form |
{object} 'string' |
application/x-www-form-urlencoded request body |
json |
{object} 'string' |
JSON encoded request body |
multipart |
{object} [array] |
multipart/form-data as object or multipart/related as array request body using request-multipart |
body |
'string' Buffer Stream |
Raw request body |
auth |
'string' ['string', 'string'] {user, pass} |
String or array of strings to replace the {auth} configuration token with, or Basic authorization as object |
oauth |
{object} |
OAuth 1.0a authorization using request-oauth |
encoding |
'string' |
Response body encoding |
redirect |
{object} |
HTTP redirect configuration |
timeout |
number |
Request timeout in milliseconds |
agent |
Agent |
HTTP agent |
Response Options
request
- buffers the response body
- decompresses
gzip
anddeflate
encoded bodies with validcontent-encoding
header - converts the response body to string using
utf8
encoding by default - tries to parse
JSON
andquerystring
encoded bodies with validcontent-type
header
Returns either String or Object.
buffer
- buffers the response body
- decompresses
gzip
anddeflate
encoded bodies with validcontent-encoding
header
Returns Buffer.
stream
Returns the response Stream.
Node Core Options
Any other HTTP request option not explicitly exposed in Purest can be passed using any of the response methods:
await google.request({socketPath: ''})
await google.buffer({socketPath: ''})
await google.stream({socketPath: ''})
Endpoint
The explicit endpoint
configuration can be accessed in various ways:
// as argument to the Purest instance
await google('youtube')
// using the option name
await google.endpoint('youtube')
// or the default method alias defined for it
await google.query('youtube')
Examples
Purest comes with a fancy logger
npm i --save-dev request-logs
DEBUG=req,res,body,json node examples/file-name.js 'example name'
| Category | Topics | Providers | Examples
| :- | :- | :- | :-
| OAuth 2.0 | Refresh Access Tokens | box
google
twitch
| Refresh access tokens
| OpenID Connect | Verify id_token | auth0
google
microsoft
| Discover public keys and verify id_token signature
| OAuth 1.0a | OAuth 1.0a | flickr
trello
twitter
| Get user profile
| Storage | Multipart, Streams | box
dropbox
drive
| Upload files
| Storage | HTTP Streams | box
dropbox
| Stream file from DropBox to Box
Get access tokens using Grant