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()

This is Purest v4, for older releases take a look at v3 and v2

• Introduction
• Purest Options
• Request Options
• Examples
• Article

Purest is a tool for building expressive REST API clients

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()

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()

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()

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 is a flexible tool for abstracting out REST APIs

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

Purest is built on top of a powerful HTTP Client

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.

• 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.

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

Returns Buffer.

Returns the response Stream.

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

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')

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