Fetch-restful NPM

FetchREST(ful)

🚀 A wrapper around fetch for REST API dependent projects.

Installation

yarn add fetch-restful

Usage

Constructor

const request = new FetchREST(
  GlobalRequestOptions | GlobalRequestOptionsGetter,
);

GlobalRequestOptions - request options that will be used as the defaults for every outgoing request.
GlobalRequestOptionsGetter - a method that returns a GlobalRequestOptions object.

Request methods.

await request.get('/users', QueryObject, RequestOptions);
await request.post('/users', Payload, RequestOptions);
await request.patch('/users', Payload, RequestOptions);
await request.put('/users', Payload, RequestOptions);
await request.delete('/users', Payload, RequestOptions);

QueryObject - object with query parameters to use.
Payload - your request payload.
RequestOptions - request options that will be merged with your global request options.

Middleware

Use the middleware method to define a function that will be added to the promise chain for all outgoing requests.

request.middleware(Middleware);

Middleware - method that will be added to the promise chain.

Examples

Basic `GET`.

const request = new FetchREST({
  apiUrl: 'https://api.github.com',
});

await request.get('/users/kvendrik');

Basic `GET` with query.

const fetchRest = new FetchREST({
  apiUrl: 'https://api.github.com',
});

await fetchRest.get('/users', {
  limit: 20,
  skip: 10,
  userIds: ['23181', '72819', '21819'],
});

Using an options getter.

const fetchRest = new FetchREST(() => ({
  apiUrl: 'https://yourapi.com',
  headers: {
    'X-Timestamp': new Date().getTime(),
  },
}));

await fetchRest.get('/users/kvendrik');

Setting global headers.

const request = new FetchREST({
  apiUrl: 'https://api.github.com',
  headers: {
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
});

await request.get('/users/kvendrik');

Locally adding and/or overriding headers.

const request = new FetchREST({
  apiUrl: 'https://api.github.com',
  headers: {
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
});

await request.get(
  '/users/kvendrik',
  {},
  {
    headers: {
      Authorization: 'Bearer xxx',
      Accept: 'text/xml',
    },
  },
);

Adding data to all responses.

const fetchRest = new FetchREST({
  apiUrl: 'https://api.github.com',
});

fetchRest.middleware(request =>
  request.then(response => ({...response, timestamp: new Date().getTime()})),
);

await fetchRest.get('/users/kvendrik');

Global and local error handling (resolved).

const fetchRest = new FetchREST({
  apiUrl: 'https://non-existent-url',
});

fetchRest.middleware(request =>
  request.catch(error => {
    console.log('ERROR', error);
    return {body: null, status: 0, success: false};
  }),
);

await fetchRest.get('/users/kvendrik');

Global and local error handling (unresolved).

const fetchRest = new FetchREST({
  apiUrl: 'https://non-existent-url',
});

fetchRest.middleware(request =>
  request.catch(error => {
    console.log('ERROR (triggered first)', error);
    throw error;
  }),
);

fetchRest
  .get('/users/kvendrik')
  .then(res => {
    console.log('RESPONSE (not triggered)', res);
  })
  .catch(error => {
    console.log('ERROR_LOCAL (triggered second)', error);
  });

Cancelling a request.

const fetchRest = new FetchREST({
  apiUrl: 'https://api.github.com',
});

const abortToken = fetchRest.getAbortToken();
fetchRest.get('/users', {}, {abortToken});
fetchRest.abort(abortToken);

Request timeout.

const fetchRest = new FetchREST({
  apiUrl: 'https://api.github.com',
});

fetchRest.get('/users', {}, {timeout: 500});

Working with multiple APIs.

const githubApi = new FetchREST({
  apiUrl: 'https://api.github.com',
});

const appApi = new FetchREST({
  apiUrl: 'https://api.yourapp.com',
});

await githubApi.get('/users');
await appApi.get('/users');