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

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

Get access tokens using Grant