Frisbee

[![Slack Status][slack-image]][slack-url] [![npm version][npm-image]][npm-url] [![npm downloads][npm-downloads]][npm-url]

:heart: Love this project? Support <a href="https://github.com/niftylettuce" target="_blank">@niftylettuce's</a> FOSS on <a href="https://patreon.com/niftylettuce" target="_blank">Patreon</a> or <a href="https://paypal.me/niftylettuce">PayPal</a> :unicorn:

Modern [fetch-based][fetch] alternative to [axios][]/[superagent][]/[request][]. Great for [React Native][react-native].

New in v2.0.4++: baseURI is now optional and you can pass raw: true as a global or request-based option to get the raw fetch() response (e.g. if you want to use res.arrayBuffer() or [any other method][fetch-methods] manually).

Table of Contents

• Install
  • Node (Koa, Express, React Native, ...)
  • Browser
• Usage
  • Example
  • API
  • Logging and Debugging
  • Common Issues
  • Required Features
• Frequently Asked Questions
  • How do I unset a default header
  • Why do my form uploads randomly fail with React Native
  • Does this support callbacks, promises, or both
  • What is the fetch method
  • Does the Browser or Node.js support fetch yet
  • If my engine does not support fetch yet, is there a polyfill
  • Can I make fetch support older browsers
  • What is this project about
  • Why not just use superagent or fetch
  • Want to build an API back-end with Node.js
  • Need help or want to request a feature
• Tests
• Development
• Background
• Contributors
• Credits
• License

Install

Node (Koa, Express, React Native, ...)

1. Install the required package:

   npm install --save frisbee
   

2. See usage example and API below

Browser

VanillaJS

1. Load the package via <script> tag (note you will need to polyfill with required features):

<script crossorigin="anonymous" src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=es6,Array.from,Object.getOwnPropertyDescriptors,Object.getOwnPropertySymbols,Promise,Promise.race,Promise.reject,Promise.resolve,Reflect,Symbol.for,Symbol.iterator,Symbol.prototype,Symbol.species,Symbol.toPrimitive,Symbol.toStringTag,Uint8Array"></script>
<script src="https://unpkg.com/frisbee"></script>
<script type="text/javascript">
  (function() {
    // create a new instance of Frisbee
    var api = new Frisbee({
      baseURI: 'https://api.startup.com', // optional
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      }
    });

    // this is a simple example using `.then` and `.catch`
    api.get('/hello-world').then(console.log).catch(console.error);

    //
    // see the Usage section below in Frisbee's README for more information
    // https://github.com/niftylettuce/frisbee
    //
  })();
</script>

2. See usage example and API below for a more complete example.

Bundler

1. Install the required package:

   npm install frisbee
   

2. Ensure that your environment is polyfilled with required features (e.g. use [@babel/polyfill][babel-polyfill] globally or a service like polyfill.io)

3. See usage example and API below

Usage

Example

const Frisbee = require('frisbee');

// create a new instance of Frisbee
const api = new Frisbee({
  baseURI: 'https://api.startup.com', // optional
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  }
});

// this is a simple example using `.then` and `.catch`
api.get('/hello-world').then(console.log).catch(console.error);

// this is a more complex example using async/await and basic auth
(async () => {
  // log in to our API with a user/pass
  try {
    // make the request
    let res = await api.post('/v1/login');

    // 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' });

    // 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');

    // 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) {
    console.error(err);
  }
})();

API

const Frisbee = require('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 (String) - the default URI to use as a prefix for all HTTP requests (optional as of v2.0.4+)

    • If your API server is running on http://localhost:8080, then use that as the value for this option

    • If you use [React Native][react-native], then you most likely want to set baseURI 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'
      });
      

    • You could also set 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)

    • Using [React Native][react-native]? You might want to read this article about [automatic IP configuration][automatic-ip-configuration].

  • headers (Object) - an object containing default headers to send with every request

    • Tip: You'll most likely want to set the "Accept" header to "application/json" and the "Content-Type" header to "application/json"

  • body (Object) - an object containing default body payload to send with every request. Either the default body set in options will be used or it will be overridden with a request provided body. Body will not merge nor deep merge.

  • params (Object) - an object containing default querystring parameters to send with every request (API method specific params options will override or extend properties defined here, but will not deep merge)

  • logRequest (Function) - a function that accepts two arguments path (String) and opts (Object) and will be called with before a fetch request is made with (e.g. fetch(path, opts) – see Logging and Debugging below for example usage) - this defaults to false so no log request function is called out of the box

  • logResponse (Function) - a function that accepts three arguments path (String), opts (Object), and response (Object) and has the same parameters as logRequest, with the exception of the third response, which is the raw response object returned from fetch (see Logging and Debugging below for example usage) - this defaults to false so no log response function is called out of the box

  • auth - will call the auth() function below and set it as a default

  • parse - options passed to qs.parse method (see [qs][qs-url] for all available options)

    • ignoreQueryPrefix (Boolean) - defaults to true, and parses querystrings from URL's properly

  • stringify - options passed to qs.stringify method (see [qs][qs-url] for all available options)

    • addQueryPrefix (Boolean) - defaults to true, and affixes the path with required ? parameter if a querystring is to be passed

    • format (String) - defaults to RFC1738

    • arrayFormat (String) - defaults to 'indices'

  • preventBodyOnMethods (Array) - defaults to [ 'GET', 'HEAD', 'DELETE', 'CONNECT' ], and is an Array of HTTP method names that we will convert a body option to be querystringified URL parameters (e.g. api.get('/v1/users', { search: 'foo' }) will result in GET /v1/users?search=foo). According to RFC 7231, the default methods defined here have no defined