purest

REST API Client Library

  • purest

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
purest
52204.0.29 months ago8 years agoMinified + gzip package size for purest in KB

Readme

Purest
!npm-versionnpm !test-ci-imgtest-ci-url !test-cov-imgtest-cov-url !snyk-vulnerabilitiessnyk
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}"
      }
    }
  }
}

Our configuration can be used to instantiate that provider:
var google = purest({provider: 'google', config})

Finally 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 static value:
var google = purest({provider: 'google', config,
  defaults: {auth: token}
})

Then we no longer need to set the access token on 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 | :- | :-: | :- | 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 Clientrequest-compose

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 objecturl-parse | 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 objecturl-parse | Proxy URL; for HTTPS you have to use tunnelingtunnel-agent agentproxy-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' Bufferbuffer Streamstream-readable | 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'buffer-encoding | Response body encoding | redirect | {object} | HTTP redirect configurationredirect-config | timeout | number | Request timeout in milliseconds | agent | Agentagent | 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 Bufferbuffer.
stream
Returns the response Streamstream-incoming-message.

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 loggerrequest-logs

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 tokensrefresh-token | OpenID Connect | Verify idtoken | auth0 google microsoft | Discover public keys and verify idtoken signatureopenid-connect | OAuth 1.0a | OAuth 1.0a | flickr trello twitter | Get user profileoauth-1 | Storage | Multipart, Streams | box dropbox drive | Upload filesfile-stream | Storage | HTTP Streams | box dropbox | Stream file from DropBox to Boxhttp-stream
Get access tokens using Grant

npm-version: https://img.shields.io/npm/v/purest.svg?style=flat-square (NPM Version) test-ci-img: https://img.shields.io/travis/simov/purest/master.svg?style=flat-square (Build Status) test-cov-img: https://img.shields.io/coveralls/simov/purest.svg?style=flat-square (Test Coverage) snyk-vulnerabilities: https://img.shields.io/snyk/vulnerabilities/npm/purest.svg?style=flat-square (Vulnerabilities)
npm: https://www.npmjs.com/package/purest test-ci-url: https://github.com/simov/purest/actions/workflows/test.yml test-cov-url: https://coveralls.io/r/simov/purest?branch=master snyk: https://snyk.io/test/npm/purest
v3: https://github.com/simov/purest/tree/3.x v2: https://github.com/simov/purest/tree/2.x article: https://dev.to/simov/purest-53k0
request-compose: https://github.com/simov/request-compose request-oauth: https://github.com/simov/request-oauth request-multipart: https://github.com/simov/request-multipart request-cookie: https://github.com/simov/request-cookie request-logs: https://github.com/simov/request-logs
grant: https://github.com/simov/grant redirect-config: https://github.com/simov/request-compose#redirect tunnel-agent: https://github.com/simov/request-compose/blob/master/examples/misc-tunnel-agent.js proxy-agent: https://github.com/simov/request-compose/blob/master/examples/misc-proxy-agent.js methods.json: https://github.com/simov/purest/blob/master/config/methods.json
refresh-token: https://github.com/simov/purest/blob/master/examples/refresh-token.js openid-connect: https://github.com/simov/purest/blob/master/examples/openid-connect.js oauth-1: https://github.com/simov/purest/blob/master/examples/oauth-1.js file-stream: https://github.com/simov/purest/blob/master/examples/file-stream.js http-stream: https://github.com/simov/purest/blob/master/examples/http-stream.js
url-parse: https://nodejs.org/dist/latest-v10.x/docs/api/url.html#urlurlparseurlstringparsequerystringslashesdenotehost buffer: https://nodejs.org/dist/latest-v10.x/docs/api/buffer.html buffer-encoding: https://nodejs.org/dist/latest-v10.x/docs/api/buffer.html#bufferbuffersandcharacterencodings stream-readable: https://nodejs.org/dist/latest-v10.x/docs/api/stream.html#streamclassstreamreadable stream-incoming-message: https://nodejs.org/dist/latest-v10.x/docs/api/http.html#httpclasshttpincomingmessage agent: https://nodejs.org/docs/latest-v10.x/api/http.html#httpclasshttpagent