http-client

Provides convenient apis to make http requests and handle the responses, eliminates boilerplate code. It is basically a wrapper over XHR requests (uses fetch).

APIs

The main API of the library is createMethod. This creates a ready to use function with some settings already embedded into it.

createMethod(method, baseUrl, defaultOptions)

Params:

| Parameter | Description | Type | Required | |----------------|-------------------------------------------------------------------------------------------------------------------------|--------|----------| | method | HTTP method: GET, POST, PUT, etc. | String | Yes | | baseUrl | Base url of the request path (will be prefixed the final url). When not specified relative path will be used / | String | No | | defaultOptions | Request options that will be used by default. See details below | Object | No |

Options:

| Parameter | Description | Type | Required | |-----------------|------------------------------------------------------------------------------------------------|---------|----------| | headers | Extra headers you would like to pass | Object | No | | withCredentials | Flag whether to include cookies in the request (defaults to false) | Boolean | No | | mode | Request mode | String | No | | params | Search params object. Will be trasnformed to query string and appended to the request url | Object | No |

createMethod returns a function with the following signature:

method(endpointUrl, body, options)

Parameters:

| Parameter | Description | Type | Required | |-------------|---------------------------------------------------------------------------------------------------------|--------|----------| | endpointUrl | The request endpoint. Will be appended to the baseUrl | String | Yes | | body | Request body | Object | No | | options | Request options. See details above. This will be merged with defaultOptions specified at createMethod | Object | No |

Example

  import { createMethod } from '@35up/http-client';
  
  const put = createMethod(
    'PUT',
    'https://my-website/apis/v1',
    {
      withCredentials: true, 
      headers: {'Content-Type': 'application/octet-stream'},
    },
   );
   
  // And then just use it to make an http request
  const result = await put('/order', {sku: '12345'}, {mode: 'cors'});

The returned value is a promise with decoded response body.

In case response fails, method throws an exception of type HttpError

HttpError inherits from Error class and has the following extra properties:

| Property | Description | Type | |--------------------|-------------------------------------------------|--------| | responseStatus | Status code (404, 500, etc.) | Number | | responseStatusText | Status text (i.e. internal server error) | String | | data | Reponse data. This may contain arbitrary object | Object |

Checking if thrown exception is of type HttpError

This is possible with isHttpError utility:

  try {
    ...
    await method(...);
  } catch(e) {
    if (isHttpError(e)) {
      // ... An http error happened. handle it here
    }
    // Some other issue occured, deal with it in other way
  }

Shortcuts

The library also exposes ready to use methods that do not have a base url so you could bypass calling createMethod in case your api base url is the same as your website (using relative path):

  import { get } from '@35up/http-client';
  
  const result = await get('/api/v1/orders');

The available functions are: get, post, put, patch, deleteMethod, head;

Requirements

The library supports both browser and node environments.

Http-client depends on the Fetch API. If you support older browsers which may not yet provide these natively (e.g. IE), consider including a global polyfill in your bundled application, such as fetch.