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

🏗 Contributing

1. Make your changes.
2. Add/Alter the appropriate tests.
3. Make sure all tests pass (yarn lint && yarn test).
4. Create a PR.