Stripe-inspired API wrapper around ES6/ES7's fetch() method for making simple HTTP requests (alternative to superagent, request, axios)
tldr; Stripe-inspired API wrapper around ES6/ES7's fetch() method for making simple HTTP requests (alternative to superagent, request, axios).
If you're using
node-fetch, you neednode-fetch@v1.5.3to useform-datawith files properly (due to https://github.com/bitinn/node-fetch/issues/102)
react-native provides us with a fetch implementation):npm install --save frisbee
Import the package:
import Frisbee from 'frisbee';
See usage example and API below.
Install the required packages:
NPM:
# optional (to support older browsers):
npm install --save es6-promise
# required (to add global `fetch` method):
npm install --save isomorphic-fetch
# required (this package):
npm install --save frisbee
Bower:
# optional (to support older browsers):
bower install --save es6-promise
# required (to add global `fetch` method):
bower install --save isomorphic-fetch
# required (this package):
bower install --save frisbee
Require it, set default options, and make some requests:
// add optional support for older browsers
import es6promise from 'es6-promise';
es6promise.polyfill();
// add required support for global `fetch` method
// *this must always come before `frisbee` is imported*
import 'isomorphic-fetch';
// require the module
import Frisbee from 'frisbee';
// create a new instance of Frisbee
const api = new Frisbee({
baseURI: 'https://api.startup.com',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
}
});
makeRequests();
async function makeRequests() {
// log in to our API with a user/pass
try {
// make the request
let res = await api.post('/v1/login');
console.log('response', res.body);
// handle HTTP or API errors
if (res.err) throw res.err;
// set basic auth headers for all
// future API requests we make
api.auth(res.body.api_token);
// now let's post a message to our API
res = await api.post('/v1/messages', { body: 'Hello' });
console.log('response', res.body);
// handle HTTP or API errors
if (res.err) throw res.err;
// now let's get a list of messages filtered by page and limit
res = await api.get('/v1/messages', {
body: {
limit: 10,
page: 2
}
});
// handle HTTP or API errors
if (res.err) throw res.err;
// now let's logout
res = api.post('/v1/logout');
console.log('response', res.body);
// handle HTTP or API errors
if (res.err) throw res.err;
// unset auth now since we logged out
api.auth();
// for more information on `fetch` headers and
// how to send and expect various types of data:
// <https://github.com/github/fetch>
} catch (err) {
throw err;
}
}
import Frisbee from 'frisbee';
Frisbee is a function that optionally accepts an argument options, which is an object full of options for constructing your API instance.
Frisbee - accepts an options object, with the following accepted options:
baseURI - the default URI to use as a prefix for all HTTP requests
http://localhost:8080, then use that as the value for this optionbaseURI as follows (e.g. making use of __DEV__ global variable):const api = new Frisbee({
baseURI: __DEV__
? process.env.API_BASE_URI || 'http://localhost:8080'
: 'https://api.startup.com'
});
API_BASE_URI as an environment variable, and then set the value of this option to process.env.API_BASE_URI (e.g. API_BASE_URI=http://localhost:8080 node app)headers - an object containing default headers to send with every request
"Accept" header to "application/json" and the "Content-Type" header to "application/json"auth - will call the auth() function below and set it as a default
arrayFormat - how to stringify array in passed body. See qs for available formats
Upon being invoked, Frisbee returns an object with the following chainable methods:
api.auth(creds) - helper function that sets BasicAuth headers, and it accepts user and pass arguments
creds user and pass as an array, arguments, or string: ([user, pass]), (user, pass), or ("user:pass"), so you shouldn't have any problems!user and pass arguments, then it removes any previously set BasicAuth headers from prior auth() callsuser, then it will set pass to an empty string ''): then it will assume you are trying to set BasicAuth headers using your own user:pass stringuser and pass anyways)api.jwt(token) - helper function that sets a JWT Bearer header. It accepts the jwt_token as a single string argument
All exposed HTTP methods return a Promise, and they require a path string, and accept an optional options object:
path required - the path for the HTTP request (e.g. /v1/login, will be prefixed with the value of baseURI mentioned earlier)options optional - an object containing options, such as header values, a request body, form data, or a querystring to send along with the request, here are a few examples:
To set a custom header value of X-Reply-To on a POST request:
const res = await api.post('/messages', {
headers: {
'X-Reply-To': '7s9inuna748y4l1azchi'
}
});
api.get(path, options) - GETapi.head(path, options) - HEAD (does not currently work - see tests)api.post(path, options) - POSTapi.put(path, options) - PUTapi.del(path, options) - DELETEapi.options(path, options) - OPTIONS (does not currently work - see tests)api.patch(path, options) - PATCHNote that you can chain the auth method and an HTTP method together:
const res = await api.auth('foo:bar').get('/');
Does this support callbacks, promises, or both?
As of version 1.0.0 we have dropped support for callbacks, it now only supports Promises.
What is the fetch method?
It is a new method introduced into the ES6 specification. You can read more about it here https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch.
Does the Browser or Node.js support fetch yet?
Yes, a lot of browsers are now supporting it! See this reference for more information http://caniuse.com/#feat=fetch.
If my engine does not support fetch yet, is there a polyfill?
Yes you can use the fetch method (polyfill) from whatwg-fetch or node-fetch.
By default, React Native already has a built-in fetch out of the box!
Can I make fetch support older browsers?
Yes, but you'll need a promise polyfill for older browsers.
What is this project about?
Use this package as a universal API wrapper for integrating your API in your client-side or server-side projects.
It's a better working alternative (and with less headaches; at least for me) – for talking to your API – than superagent and the default fetch Network method provide.
Use it for projects in Node, React, Angular, React Native, ...
It supports and is tested for both client-side usage (e.g. with Bower, Browserify, or Webpack, with whatwg-fetch) and also server-side (with node-fetch).
Why not just use superagent or fetch?
See Background for more information.
Want to build an API back-end with Node.js?
See CrocodileJS as a great starting point, and read this article about building Node.js API's with authentication.
Need help or want to request a feature?
File an issue on GitHub and we'll try our best help you out.
Why don't you have an ES5 compiled version readily available in this git repo?
As this module relies on ES6 fetch, there is currently no backwards compatibility for ES5
This package is tested to work with whatwg-fetch and node-fetch.
This means that it is compatible for both client-side and server-side usage.
npm installnpm run watch to watch the src directory for changessrc directory/test/ if you add more stuffnpm test when you're doneThe docs suggest that you use superagent with React Native, but in our experience it did not work properly, therefore we went with the next best solution, the Github fetch API polyfill included with React Native. After having several issues trying to use fetch and writing our own API wrapper for a project with it (and running into roadblocks along the way) – we decided to publish this.
Here were the issues we discovered/filed related to this:
We know that solutions like superagent exist, but they don't seem to work well with React Native (which was our use case for this package).
In addition, the authors of the spec for ES6's fetch support throwing errors instead of catching them and bubbling them up to the callback/promise (for example, with Frisbee any HTTP or API errors are found in the res.err object).
Therefore we created frisbee to serve as our API glue, and hopefully it'll serve as yours too.
fetch-api, and frisbee was surprisingly available on NPM)FAQs
Modern fetch-based alternative to axios/superagent/request. Great for React Native.
The npm package frisbee receives a total of 781 weekly downloads. As such, frisbee popularity was classified as not popular.
We found that frisbee demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Malicious PyPI package semantic-types steals Solana private keys via transitive dependency installs using monkey patching and blockchain exfiltration.
Security News
New CNA status enables OpenJS Foundation to assign CVEs for security vulnerabilities in projects like ESLint, Fastify, Electron, and others, while leaving disclosure responsibility with individual maintainers.
Product
Socket MCP brings real-time security checks to AI-generated code, helping developers catch risky dependencies before they enter the codebase.