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 Options
• Request Options
• Examples
• Article

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: {}})

Request Options

Purest is built on top of a powerful HTTP Client

URL Options

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

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'

Get access tokens using Grant

Change Log

v4.0.3 (2022/12/22)

• Change: Update deps and docs

v4.0.2 (2022/03/12)

• Fix: Bump deps

v4.0.1 (2021/03/15)

• Change: Update type definitions

v4.0.0 (2021/02/08)

• New: Complete rewrite of the module

v3.1.0 (2016/12/21)

• New: defer option

v3.0.1 (2016/07/17)

• Fix: absolute url detection

v3.0.0 (2016/07/17)

• New: Breaking Changes
• Change: The request module is no longer an internal dependency of Purest, it should be installed separately and passed to Purest.
• Change: The provider's configuration is no longer part of the module, it should be installed separately and passed through the config option.
• Change: The new keyword is no longer used when creating a new provider instance.
• Change: The api constructor option is now called alias.
• Change: The api option for the Basic API is now also called alias.
• Change: By default the constructor now returns an instance of the Chain API.
• Change: The Basic API can be enabled explicitly through the api: 'basic' options of the constructor.
• Change: The query() method of the Chain API is no longer required to initiate the Chain API, use it only if you need to specify the path alias to use.
• Change: The Promise implementation have to be passed as dependency when initializing Purest.
• Change: The debug option is no longer available for the constructor.
• Change: The defaults options passed in the constructor are being extended in Purest instead of in request.
• Change: The default Chain API method aliases were removed, for example: post-update and so on.
• Change: The before hook methods and the hooks options in the constructor are no longer available.
• Change: Versions of Node below version 4.0 LTS are no longer supported.
• Change: - Change: Version 3.0 of Purest is licensed under the Apache 2.0 license.

v2.0.1 (2016/03/02)

• Fix: support for Bluebird 3

v2.0.0 (2015/08/06)

• Fix: before request hooks
• Fix: user defined method aliases
• Fix: support for Promises
• Fix: official support of 40+ more providers
• Change: renamed the domain path modifier to subdomain
• Change: removed the __provider key from the configuration

v1.2.0 (2015/06/16)

• Change: the refresh method and config are no longer available - use the Query API instead
• Change: __provider and __domain meta keys are no longer required

v1.0.0 (2014/06/23)

• Initial Release