{"id":13453851,"url":"https://github.com/simov/purest","last_synced_at":"2025-05-15T13:05:38.813Z","repository":{"id":18064850,"uuid":"21124822","full_name":"simov/purest","owner":"simov","description":"REST API Client Library","archived":false,"fork":false,"pushed_at":"2024-01-15T17:48:35.000Z","size":958,"stargazers_count":560,"open_issues_count":3,"forks_count":24,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-05-15T06:02:41.746Z","etag":null,"topics":["api","client","http","https","javascript","js","node","nodejs","rest"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simov.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-06-23T12:05:09.000Z","updated_at":"2025-05-14T08:57:08.000Z","dependencies_parsed_at":"2023-01-13T19:38:22.347Z","dependency_job_id":"3f2ae83c-14b3-44b8-bc5d-a18db7a5c4fc","html_url":"https://github.com/simov/purest","commit_stats":{"total_commits":680,"total_committers":3,"mean_commits":"226.66666666666666","dds":0.004411764705882337,"last_synced_commit":"bc57fc4c8608c24d63f6e05fe85d409949882af8"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simov%2Fpurest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simov%2Fpurest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simov%2Fpurest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simov%2Fpurest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simov","download_url":"https://codeload.github.com/simov/purest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346624,"owners_count":22055808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","client","http","https","javascript","js","node","nodejs","rest"],"created_at":"2024-07-31T08:00:48.508Z","updated_at":"2025-05-15T13:05:38.784Z","avatar_url":"https://github.com/simov.png","language":"JavaScript","readme":"\n# Purest\n\n[![npm-version]][npm] [![test-ci-img]][test-ci-url] [![test-cov-img]][test-cov-url] [![snyk-vulnerabilities]][snyk]\n\n\u003e _REST API Client Library_\n\n```js\nvar purest = require('purest')\nvar google = purest({provider: 'google'})\n\nawait google\n  .query('youtube')\n  .select('channels')\n  .where({forUsername: 'GitHub'})\n  .auth(token)\n  .request()\n```\n\n## Table of Contents\n\n\u003e _This is Purest **v4**, for older releases take a look at [v3] and [v2]_\n\n- **[Introduction](#introduction)**\n- **[Purest Options](#purest-options)**\n- **[Request Options](#request-options)**\n- **[Examples](#examples)**\n- **[Article]**\n\n---\n\n## Introduction\n\n\u003e _**Purest** is a tool for building **expressive** REST API clients_\n\n### Default Endpoint\n\nHere is a basic configuration for Google:\n\n```json\n{\n  \"google\": {\n    \"default\": {\n      \"origin\": \"https://www.googleapis.com\",\n      \"path\": \"{path}\",\n      \"headers\": {\n        \"authorization\": \"Bearer {auth}\"\n      }\n    }\n  }\n}\n```\n\nThe above configuration can be used to instantiate that provider:\n\n```js\nvar google = purest({provider: 'google', config})\n```\n\nThen we can request some data from YouTube:\n\n```js\nvar {res, body} = await google\n  .get('youtube/v3/channels')\n  .qs({forUsername: 'GitHub'})\n  .auth(token)\n  .request()\n```\n\n### Explicit Endpoint\n\nWe can define explicit endpoint for accessing the YouTube API:\n\n```json\n{\n  \"google\": {\n    \"default\": {\n      \"origin\": \"https://www.googleapis.com\",\n      \"path\": \"{path}\",\n      \"headers\": {\n        \"authorization\": \"Bearer {auth}\"\n      }\n    },\n    \"youtube\": {\n      \"origin\": \"https://www.googleapis.com\",\n      \"path\": \"youtube/{version}/{path}\",\n      \"version\": \"v3\",\n      \"headers\": {\n        \"authorization\": \"Bearer {auth}\"\n      }\n    }\n  }\n}\n```\n\nAnd then request the same data:\n\n```js\nvar {res, body} = await google('youtube')\n  .get('channels')\n  .qs({forUsername: 'GitHub'})\n  .auth(token)\n  .request()\n```\n\n### Defaults\n\nEvery method in Purest can also be preconfigured with a value:\n\n```js\nvar google = purest({provider: 'google', config,\n  defaults: {auth: token}\n})\n```\n\nThen we no longer need to set the access token on each request:\n\n```js\nvar {res, body} = await google('youtube')\n  .get('channels')\n  .qs({forUsername: 'GitHub'})\n  .request()\n```\n\n### Method Aliases\n\nEach method in Purest can have multiple aliases defined for it:\n\n```js\nvar google = purest({provider: 'google', config,\n  defaults: {auth: token},\n  methods: {get: ['select'], qs: ['where']}\n})\n```\n\nAnd then use it like this:\n\n```js\nvar {res, body} = await google('youtube')\n  .select('channels')\n  .where({forUsername: 'GitHub'})\n  .request()\n```\n\n---\n\n## Purest Options\n\n\u003e _**Purest** is a flexible tool for **abstracting** out REST APIs_\n\n```js\nvar google = purest({config: {}, provider: 'google', defaults: {}, methods: {}})\n```\n\n| Key            | Type | Description\n| :-             | :-:  | :-\n| **`provider`** | `''` | Provider name to initialize from the list of providers found in `config`\n| **`config`**   | `{}` | Providers configuration to use\n| **`defaults`** | `{}` | Any supported configuration option set by default, see below\n| **`methods`**  | `{}` | List of methods and their aliases to use with this instance\n\n---\n\n## Request Options\n\n\u003e _**Purest** is built on top of a **[powerful HTTP Client][request-compose]**_\n\n### URL Options\n\n| Option      | Description\n| :-          | :-\n| `origin`    | The protocol and domain part of the URL, can contain `{subdomain}` token\n| `path`      | The path part of the URL, can contain `{version}`, `{path}` and `{type}` tokens\n| `subdomain` | Subdomain part of the URL to replace in `origin`\n| `version`   | Version string to replace in `path`\n| `type`      | Type string to replace in `path`, typically `json` or `xml`\n\n### HTTP Methods\n\nAll 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`.\n\n### Request Options\n\n| Option     | Type                  | Description\n| :--        | :--                   | :--\n| `method`   | `'string'` | Request method, implicitly set if one of the above HTTP Methods is used\n| `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\n| `proxy`    | `'string'` [`url object`][url-parse] | Proxy URL; for HTTPS you have to use [tunneling][tunnel-agent] [agent][proxy-agent] instead\n| `qs`       | `{object}` `'string'` | URL querystring\n| `headers`  | `{object}` | Request headers\n| `form`     | `{object}` `'string'` | `application/x-www-form-urlencoded` request body\n| `json`     | `{object}` `'string'` | JSON encoded request body\n| `multipart`| `{object}` `[array]`  | `multipart/form-data` as object or `multipart/related` as array request body using [request-multipart]\n| `body`     | `'string'` [`Buffer`][buffer] [`Stream`][stream-readable] | Raw request body\n| `auth`     | `'string'` `['string', 'string']` `{user, pass}`        | String or array of strings to replace the `{auth}` configuration token with, or Basic authorization as object\n| `oauth`    | `{object}` | OAuth 1.0a authorization using [request-oauth]\n| `encoding` | [`'string'`][buffer-encoding] | Response body encoding\n| `redirect` | `{object}` | HTTP redirect [configuration][redirect-config]\n| `timeout`  | `number` | Request timeout in milliseconds\n| `agent`    | [`Agent`][agent] | HTTP agent\n\n### Response Options\n\n#### `request`\n\n- buffers the response body\n- decompresses `gzip` and `deflate` encoded bodies with valid `content-encoding` header\n- converts the response body to string using `utf8` encoding by default\n- tries to parse `JSON` and `querystring` encoded bodies with valid `content-type` header\n\nReturns either String or Object.\n\n#### `buffer`\n\n- buffers the response body\n- decompresses `gzip` and `deflate` encoded bodies with valid `content-encoding` header\n\nReturns [Buffer][buffer].\n\n#### `stream`\n\nReturns the response [Stream][stream-incoming-message].\n\n### Node Core Options\n\nAny other HTTP request option not explicitly exposed in Purest can be set using any of the response methods:\n\n```js\nawait google.request({socketPath: ''})\nawait google.buffer({socketPath: ''})\nawait google.stream({socketPath: ''})\n```\n\n### Endpoint\n\nThe explicit `endpoint` configuration can be accessed in various ways:\n\n```js\n// as argument to the Purest instance\nawait google('youtube')\n// using the option name\nawait google.endpoint('youtube')\n// or the default method alias defined for it\nawait google.query('youtube')\n```\n\n---\n\n## Examples\n\n\u003e _**Purest** comes with a **[fancy logger][request-logs]**_\n\n```bash\nnpm i --save-dev request-logs\n```\n\n```bash\nDEBUG=req,res,body,json node examples/file-name.js 'example name'\n```\n\n| Category | Topic | Providers | Example\n| :-       | :-    | :-        | :-\n| **OAuth 2.0** | _Refresh Access Tokens_ | `box` `google` `twitch` | [Refresh access tokens][refresh-token]\n| **OpenID Connect** | *Verify id_token* | `auth0` `google` `microsoft` | [Discover public keys and verify id_token signature][openid-connect]\n| **OAuth 1.0a** | _OAuth 1.0a_ | `flickr` `trello` `twitter` | [Get user profile][oauth-1]\n| **Storage** | _Multipart, Streams_ | `box` `dropbox` `drive` | [Upload files][file-stream]\n| **Storage** | _HTTP Streams_ | `box` `dropbox` | [Stream file from DropBox to Box][http-stream]\n\n\u003e _Get access tokens using **[Grant]**_\n\n\n  [npm-version]: https://img.shields.io/npm/v/purest.svg?style=flat-square (NPM Version)\n  [test-ci-img]: https://img.shields.io/travis/simov/purest/master.svg?style=flat-square (Build Status)\n  [test-cov-img]: https://img.shields.io/coveralls/simov/purest.svg?style=flat-square (Test Coverage)\n  [snyk-vulnerabilities]: https://img.shields.io/snyk/vulnerabilities/npm/purest.svg?style=flat-square (Vulnerabilities)\n\n  [npm]: https://www.npmjs.com/package/purest\n  [test-ci-url]: https://github.com/simov/purest/actions/workflows/test.yml\n  [test-cov-url]: https://coveralls.io/r/simov/purest?branch=master\n  [snyk]: https://snyk.io/test/npm/purest\n\n  [v3]: https://github.com/simov/purest/tree/3.x\n  [v2]: https://github.com/simov/purest/tree/2.x\n  [article]: https://dev.to/simov/purest-53k0\n\n  [request-compose]: https://github.com/simov/request-compose\n  [request-oauth]: https://github.com/simov/request-oauth\n  [request-multipart]: https://github.com/simov/request-multipart\n  [request-cookie]: https://github.com/simov/request-cookie\n  [request-logs]: https://github.com/simov/request-logs\n\n  [grant]: https://github.com/simov/grant\n  [redirect-config]: https://github.com/simov/request-compose#redirect\n  [tunnel-agent]: https://github.com/simov/request-compose/blob/master/examples/misc-tunnel-agent.js\n  [proxy-agent]: https://github.com/simov/request-compose/blob/master/examples/misc-proxy-agent.js\n  [methods.json]: https://github.com/simov/purest/blob/master/config/methods.json\n\n  [refresh-token]: https://github.com/simov/purest/blob/master/examples/refresh-token.js\n  [openid-connect]: https://github.com/simov/purest/blob/master/examples/openid-connect.js\n  [oauth-1]: https://github.com/simov/purest/blob/master/examples/oauth-1.js\n  [file-stream]: https://github.com/simov/purest/blob/master/examples/file-stream.js\n  [http-stream]: https://github.com/simov/purest/blob/master/examples/http-stream.js\n\n  [url-parse]: https://nodejs.org/dist/latest-v10.x/docs/api/url.html#url_url_parse_urlstring_parsequerystring_slashesdenotehost\n  [buffer]: https://nodejs.org/dist/latest-v10.x/docs/api/buffer.html\n  [buffer-encoding]: https://nodejs.org/dist/latest-v10.x/docs/api/buffer.html#buffer_buffers_and_character_encodings\n  [stream-readable]: https://nodejs.org/dist/latest-v10.x/docs/api/stream.html#stream_class_stream_readable\n  [stream-incoming-message]: https://nodejs.org/dist/latest-v10.x/docs/api/http.html#http_class_http_incomingmessage\n  [agent]: https://nodejs.org/docs/latest-v10.x/api/http.html#http_class_http_agent\n","funding_links":[],"categories":["Packages","JavaScript","包"],"sub_categories":["HTTP"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimov%2Fpurest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimov%2Fpurest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimov%2Fpurest/lists"}