ApiReader

⚠️ This package is deprecated in favor of Wretch ⚠️

Description

ApiReader is a NodeJS & Browser package meant to simplify your requests to any Api. Browser version is based on native fetch to be as tiny as possible if you use treechecking in your toolbelt (like webpack, create-react-app, ...). It features:

API base url recording at constuction for smaller calls
automatic query string stringification (based on qs)
automatic request body JSON stringifying based body type (objects are stringified)
automatic response body JSON parsing based on the Content-Type of the Api response
automatic base64 encoding on Basic Authentication
custom http error handling hook

Acknowledgment

Most of the code structure and part of the code is inspired from the great bent package. If you don't know it, check it out !

Installation

$ npm install @sagacify/api-reader

Usage

In your project (Browser or NodeJS)

const { ApiReader } = require('@sagacify/api-reader');
// OR
import { ApiReader } from '@sagacify/api-reader';

const main = () => {
  const bearerToken = 'super-secret-token';
  const apiReader = new ApiReader('https://api.twitter.com/2/', {
    headers: {
      authorization: `Bearer ${bearerToken}`
    },
    httpErrorHandler: (req, res) => {
      console.error(`My custom error ${res.status} for ${req.method} on ${req.url}`)
    }
  });

  try {
    const result = await apiReader.get('/2/tweets', {
      query: {
        id: 'some-tweet-id'
      },
    });

    console.log(result);
  } catch (err) {
    // This is an unexpected error, like an network issue
    console.error(err);
  }
}

main();

Note: based on the context either the Browser or the NodeJS version will be used

API

constructor(baseUrl, options)

Parameters

baseUrl: the base url of the api (e.g.: https://api.twitter.com/2/)
options:
- auth:
  - username: the username of the Basic Authentication
  - password: the password of the Basic Authentication
- headers:
  - [header-name]: header value
- queryOptions: query stringification is based on the qs stringify package, here you can pass any qs option you need
- preRequestHandler: a pre-request handler function which recieve the fetch options and must return the final fetch options:
```
{
  method: <string>, // in uppercase
  headers: <Headers>, // see: https://developer.mozilla.org/fr/docs/Web/API/Headers
  body: <string | object>
}
```
  Note: if the final fetchOptions.body is an objet, it will be JSON stringified automatically and the Content-Type will set to "application/json"
- httpErrorHandler: an http error handler function which recieve the request object.
  
  The reponse object is a simplified plain version of Response:
```
{
  url: <string>,
  method: <string>,
  headers: <object>,
  body: <string | object>
}
```
  and the response object The reponse object is a simplified plain version of Response:
```
{
  url: <string>,
  status: <number>,
  ok: <boolean>,
  redirected: <boolean>,
  type: <string>,
  headers: <object>,
  body: <string | object> // depend on the parsing
}
```
  By default any error will generate a basic error with the code field set to "HTTP_${response.status}"

head(path, options)

Performs an HEAD request to the api