Skip to content

simov/purest

Repository files navigation

Purest

npm-version test-ci-img test-cov-img snyk-vulnerabilities

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 building 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}"
      }
    }
  }
}

The above configuration can be used to 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 the YouTube API:

{
  "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}"
      }
    }
  }
}

And then request the same data:

var {res, body} = await google('youtube')
  .get('channels')
  .qs({forUsername: 'GitHub'})
  .auth(token)
  .request()

Defaults

Every method in Purest can also be preconfigured with a value:

var google = purest({provider: 'google', config,
  defaults: {auth: token}
})

Then we no longer need to set the access token on each request:

var {res, body} = await google('youtube')
  .get('channels')
  .qs({forUsername: 'GitHub'})
  .request()

Method Aliases

Each method in Purest can have multiple aliases defined for it:

var google = purest({provider: 'google', config,
  defaults: {auth: token},
  methods: {get: ['select'], qs: ['where']}
})

And then use it like this:

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
provider '' Provider name to initialize from the list of providers found in config
config {} Providers configuration to use
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 set 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 and deflate encoded bodies with valid content-encoding header
  • converts the response body to string using utf8 encoding by default
  • tries to parse JSON and querystring encoded bodies with valid content-type header

Returns either String or Object.

buffer

  • buffers the response body
  • decompresses gzip and deflate encoded bodies with valid content-encoding header

Returns Buffer.

stream

Returns the response Stream.

Node Core Options

Any other HTTP request option not explicitly exposed in Purest can be set 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 Topic Providers Example
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