ip-api-client

A small wrapper around fetch that throws custom HTTP errors.

setup

Install via npm:

  npm i -S @financial-times/ip-api-client

usage

A common pattern for fetch with async await looks like the below:

try{
  const { AMAZING_KEY: API_KEY } = process.env
  const response = await fetch('http://www.amazing.com/awesome-json', {
    method: 'POST',
    headers: {  API_KEY, 'content-type': 'application/json' },
    body: { awesomeness: 9000 }
  })

  if(response.status === 200) {
    console.log( await response.json())
  } else {
    // deal with the fetch error somehow
    throw Error('fetch failed for some reason')
  }
} catch(err) {
  // handle the URL/fetch error somehow e.g pass it to an error handler middleware in express
  next(err);
}

This module wraps much of that pattern and throws custom HTTP Errors if fetch fails.

const { create } = require('@financial-times/ip-api-client')
const { AMAZING_KEY: API_KEY } = process.env
const api = create('http://www.amazing.com', { headers: { 'content-type': 'application/json', 'API_KEY': 'AWESOME-KEY' }}, { bodyParser: 'text', errorParser: 'json', fetch: window.fetch})

try{
  const result = await api.post('/awesome-json', { body: { awesomeness: 9000 } }
  console.log(result) // receives a JSON object
} catch(err) {
  // will receive an HTTP Error with a status and name e.g. status: 404, name: NotFound
  next(err)
}

methods

createMethod

Returns a function with a canned configuration for querying an api.

method

The HTTP Verb to be used for the request e.g GET

baseUrl

The base url for requests, should be parsable by URL. This should include the protocol, hostname and port used by the request, it can also contain a partial pathname.

opts

Additional options:

• fetch - the fetch implementation to use (default: isomorphic-fetch)
• bodyParser - the body mixin function to use (default: json)
• errorParser - the body mixin function to use for error responses (default: bodyParser setting)

Returns a method used to make an http request taking following arguments:

• pathname - this will be concatenated onto the base url
• options - an object of fetch options, this is merged with the config options passed to create the init argument for the request

config = {}

Base init for fetch requests, use for things like api key headers which need to be the same on every request.

createAll

Maps all provided verbs to the method returned by createMethod, returns an object of schema { [verb]: method }.

baseUrl

Same as above

opts = {}

Same as above

config

Same as above

verbs

The verbs to create methods for, defaults to the list in http.json, which is also the list provided by the node http module.

create

Same as createAll above except the returned object also contains the HTTPErrors object.

HTTP Errors

The HttpErrors object contains a set of custom errors based on HTTP status codes, they extend the usual JS Error type but also include a status code and name e.g. status 400 name BadRequest.