Purest

[![npm-version]][npm] [![test-ci-img]][test-ci-url] [![test-cov-img]][test-cov-url] [![snyk-vulnerabilities]][snyk]

> _REST API Client Library_

``js 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_

`$3`

Here is a basic configuration for Google:

`json { "google": { "default": { "origin": "https://www.googleapis.com", "path": "{path}", "headers": { "authorization": "Bearer {auth}" } } } }`

The above configuration can be used to instantiate that provider:

`js var google = purest({provider: 'google', config})`

Then we can request some data from YouTube:

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

`$3`

We can define explicit endpoint for accessing the YouTube API:

`json { "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:

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

`$3`

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

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

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

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

`$3`

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

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

And then use it like this:

`js var {res, body} = await google('youtube') .select('channels') .where({forUsername: 'GitHub'}) .request()`

---

`Purest Options`

> _Purest is a flexible tool for abstracting out REST APIs_

`js 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][request-compose]_

`$3`

| 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

`$3`

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.

`$3`

| Option | Type | Description | :-- | :-- | :-- |method | 'string'| Request method, implicitly set if one of the above HTTP Methods is used |url | 'string' [url object][url-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 object][url-parse] | Proxy URL; for HTTPS you have to use [tunneling][tunnel-agent] [agent][proxy-agent] instead |qs | {object} 'string'| URL querystring |headers | {object}| Request headers |form | {object} 'string' | application/x-www-form-urlencodedrequest body |json | {object} 'string'| JSON encoded request body |multipart| {object} [array] | multipart/form-data as object or multipart/relatedas array request body using [request-multipart] |body | 'string' [Buffer][buffer] [Stream][stream-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 [configuration][redirect-config] |timeout | number| Request timeout in milliseconds |agent | [Agent][agent] | HTTP agent

`$3`

#### request

- buffers the response body - decompressesgzip and deflate encoded bodies with valid content-encodingheader - converts the response body to string usingutf8encoding by default - tries to parseJSON and querystring encoded bodies with valid content-type header

Returns either String or Object.

#### buffer

- buffers the response body - decompressesgzip and deflate encoded bodies with valid content-encoding header

Returns [Buffer][buffer].

#### stream

Returns the response [Stream][stream-incoming-message].

`$3`

Any other HTTP request option not explicitly exposed in Purest can be set using any of the response methods:

`js await google.request({socketPath: ''}) await google.buffer({socketPath: ''}) await google.stream({socketPath: ''})`

`$3`

The explicit endpoint configuration can be accessed in various ways:

`js // 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][request-logs]_

`bash npm i --save-dev request-logs`

`bash DEBUG=req,res,body,json node examples/file-name.js 'example name'`

> _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#url_url_parse_urlstring_parsequerystring_slashesdenotehost
[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#buffer_buffers_and_character_encodings
[stream-readable]: https://nodejs.org/dist/latest-v10.x/docs/api/stream.html#stream_class_stream_readable
[stream-incoming-message]: https://nodejs.org/dist/latest-v10.x/docs/api/http.html#http_class_http_incomingmessage
[agent]: https://nodejs.org/docs/latest-v10.x/api/http.html#http_class_http_agent

Purest

[![npm-version]][npm] [![test-ci-img]][test-ci-url] [![test-cov-img]][test-cov-url] [![snyk-vulnerabilities]][snyk]

> _REST API Client Library_

``js 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_

`$3`

Here is a basic configuration for Google:

`json { "google": { "default": { "origin": "https://www.googleapis.com", "path": "{path}", "headers": { "authorization": "Bearer {auth}" } } } }`

The above configuration can be used to instantiate that provider:

`js var google = purest({provider: 'google', config})`

Then we can request some data from YouTube:

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

`$3`

We can define explicit endpoint for accessing the YouTube API:

And then request the same data:

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

`$3`

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

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

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

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

`$3`

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

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

And then use it like this:

`js var {res, body} = await google('youtube') .select('channels') .where({forUsername: 'GitHub'}) .request()`

---

`Purest Options`

> _Purest is a flexible tool for abstracting out REST APIs_

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

---

`Request Options`

> _Purest is built on top of a [powerful HTTP Client][request-compose]_

`$3`

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.

`$3`

#### request

Returns either String or Object.

#### buffer

- buffers the response body - decompressesgzip and deflate encoded bodies with valid content-encoding header

Returns [Buffer][buffer].

#### stream

Returns the response [Stream][stream-incoming-message].

`$3`

Any other HTTP request option not explicitly exposed in Purest can be set using any of the response methods:

`js await google.request({socketPath: ''}) await google.buffer({socketPath: ''}) await google.stream({socketPath: ''})`

`$3`

The explicit endpoint configuration can be accessed in various ways:

---

`Examples`

> _Purest comes with a [fancy logger][request-logs]_

`bash npm i --save-dev request-logs`

`bash DEBUG=req,res,body,json node examples/file-name.js 'example name'`

> _Get access tokens using [Grant]_

[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