API Operations

A lightweight (5kb minified) library for simple RESTful API operations that leverages fetch.

Features

• Minimal yet powerful API
• Uses the fetch standard so it returns promises and keeps things idiomatic
• Automatic parsing of JSON data; falls back to plain text
• Standardized errors by default or configure the error output to your taste
• Rejects by default on response.status < 200 && response.status > 300, but you can configure the validation to your needs

Installing

installing api-operations via npm:

npm install api-operations

api-operations uses the fetch standard: you should bring your favorite polyfill ;D

(and fetch uses Promise, so you might need to polyfill that too, consult your polyfill of choice docs)

# official fetch polyfill - https://github.com/github/fetch
npm install whatwg-fetch

# node-fetch - https://github.com/bitinn/node-fetch
npm install node-fetch

# isomorphic-fetch - https://github.com/matthew-andrews/isomorphic-fetch
npm install isomorphic-fetch

UMD build

you can get the development and minified production files on the 'dist' folder. The library namespace is apiOperations

Getting started

import { get, postJson, createApiSource } from 'api-operations'

// Simple get json from url
get('http://myCoolApi.com/endpoint')
  .then(json => { console.log('got the json:', json) })
  .catch(error => { console.log('got an error:', error) })

// Simple post json to url
postJson('http://myCoolApi.com/endpoint', { myData: 'omgBbqWtfKawaii' })
  .then(json => { console.log('posted and got json:', json) })
  .catch(error => { console.log('posted and got error:', error) })


// Creating an API source for quick and convenient use
const myAPISource = createApiSource('http://myCoolApi.com/resource')

// Get from 'http://myCoolApi.com/resource/someEndpoint'
myAPISource.get('someEndpoint')
  .then(json => { console.log('got the json:', json) })
  .catch(error => { console.log('got an error:', error) })

// Put to 'http://myCoolApi.com/resource/someOtherEndpoint'
myAPISource.putJson('someOtherEndpoint', { myData: 'omgBbqWtfKawaii' })
  .then(json => { console.log('posted and got json:', json) })
  .catch(error => { console.log('posted and got error:', error) })

// Get from 'http://myCoolApi.com/resource'
myAPISource.get()
  .then(json => { console.log('got the json:', json) })
  .catch(error => { console.log('got an error:', error) })

API

• Methods:

  • get (url[, fetchOptions[, operationOptions]])
  • getQuery (url, query,[, fetchOptions[, operationOptions]])
  • postJson (url, body[, fetchOptions[, operationOptions]])
  • putJson (url, body[, fetchOptions[, operationOptions]])
  • patchJson (url, body[, fetchOptions[, operationOptions]])
  • sendJson (url, body[, fetchOptions[, operationOptions]])
  • delete_ (url[, fetchOptions[, operationOptions]])
  • createApiSource (baseUrl[, baseFetchOptions[, baseOperationOptions]])

• Arguments:

  • url / baseUrl / endPoint
  • fetchOptions
  • operationOptions

Methods

statusValidator and errorParser definitions omitted from examples for clarity; check the Arguments > operationOptions section for details

get (url[, fetchOptions[, operationOptions]])

Gets a document using the 'get' HTTP method and returns a promise with a parsed result. Example:

get('http://myCoolApi.com/endpoint',
  { credentials: 'same-origin' },
  { statusValidator, errorParser })
  .then(json => { console.log('got the json:', json) })
  .catch(error => { console.log('got an error:', error) })

getQuery (url, query[, fetchOptions[, operationOptions]])

Parses query object and gets a document using the 'get' HTTP method and returns a promise with a parsed result. This utility method is useful when you have complex query params that you don't want to just hardcore in the url Example:

// gets http://myCoolApi.com/endpoint?page=6&active=true
getQuery('http://myCoolApi.com/endpoint',
  { page: 6, active: true }
  { credentials: 'same-origin' },
  { statusValidator, errorParser })
  .then(json => { console.log('got the json:', json) })
  .catch(error => { console.log('got an error:', error) })

You can also append query params to the url if that's your thing

// gets http://myCoolApi.com/endpoint?foo=bar&page=6&active=true
getQuery('http://myCoolApi.com/endpoint?foo=bar',
  { page: 6, active: true }
  { credentials: 'same-origin' },
  { statusValidator, errorParser })
  .then(json => { console.log('got the json:', json) })
  .catch(error => { console.log('got an error:', error) })

postJson (url, body[, fetchOptions[, operationOptions]])

Sends a JSON body using the 'post' HTTP method and returns a promise with a parsed result. body gets converted to json automatically. Example:

postJson('http://myCoolApi.com/endpoint',
  { myData: 'omgBbqWtfKawaii' },
  { credentials: 'same-origin' },
  { statusValidator, errorParser })
  .then(json => { console.log('posted and got json:', json) })
  .catch(error => { console.log('posted and got error:', error) })

putJson (url, body[, fetchOptions[, operationOptions]])

Sends a JSON body using the 'put' HTTP method and returns a promise with a parsed result. body gets converted to json automatically. Example:

putJson('http://myCoolApi.com/endpoint',
  { myData: 'omgBbqWtfKawaii' },
  { credentials: 'same-origin' },
  { statusValidator, errorParser })
  .then(json => { console.log('put and got json:', json) })
  .catch(error => { console.log('put and got error:', error) })

patchJson (url, body[, fetchOptions[, operationOptions]])

Sends a JSON body using the 'patch' HTTP method and returns a promise with a parsed result. body gets converted to json automatically. Example:

patchJson('http://myCoolApi.com/endpoint',
  { myData: 'omgBbqWtfKawaii' },
  { credentials: 'same-origin' },
  { statusValidator, errorParser })
  .then(json => { console.log('patched and got json:', json) })
  .catch(error => { console.log('patched and got error:', error) })

sendJson (url, body[, fetchOptions[, operationOptions]])

Generic method to send a JSON body, it doesn't set any HTTP method by itself so it's useful if you want to use a non-standard/non-supported method or want to extend functionality. returns a promise with a parsed result. body gets converted to json automatically. Example:

sendJson('http://myCoolApi.com/endpoint',
  { myData: 'omgBbqWtfKawaii' },
  { method: 'SOME_METHOD', credentials: 'same-origin' },
  { statusValidator, errorParser })
  .then(json => { console.log('sent and got json:', json) })
  .catch(error => { console.log('sent and got error:', error) })

delete_ (url[, fetchOptions[, operationOptions]])

Sends a request using the 'delete' HTTP method and returns a promise with a parsed result. Example:

// we use 'delete_' because 'delete' is a reserved keyword
delete_('http://myCoolApi.com/endpoint',
  { credentials: 'same-origin' },
  { statusValidator, errorParser })
  .then(json => { console.log('deleted and got json:', json) })
  .catch(error => { console.log('deleted and got error:', error) })

createApiSource (baseUrl, [baseFetchOptions[, baseOperationOptions]])

Creates an 'API source' which acts as a base URL and base configurations for operations. Returns an object with the following endpoint methods:

• get (endPoint[, fetchOptions[, operationOptions]])
• getQuery (endPoint, query[, fetchOptions[, operationOptions]])
• postJson (endPoint, body[, fetchOptions[, operationOptions]])
• putJson (endPoint, body[, fetchOptions[, operationOptions]])
• patchJson (endPoint, body[, fetchOptions[, operationOptions]])
• sendJson (endPoint, body[, fetchOptions[, operationOptions]])
• delete (endPoint[, fetchOptions[, operationOptionsions]])

All endpoint method options get merged with the base options created by createApiSource

// Creating an API source for quick and convenient use
const myAPISource = createApiSource('http://myCoolApi.com',
                                    { credentials: 'same-origin' },
                                    { statusValidator, errorParser })

// Get from 'http://myCoolApi.com/someEndpoint' with 'same-origin' credentials,
//  custom  statusValidator and errorParser
myAPISource.get('someEndpoint')
  .then(json => { console.log('got the json:', json) })
  .catch(error => { console.log('got an error:', error) })

// Post to 'http://myCoolApi.com/someOtherEndpoint' with 'same-origin' credentials,
//  connection 'keep-alive', custom statusValidator and errorParser
myAPISource.postJson('someOtherEndpoint',
  { myData: 'omgBbqWtfKawaii' },
  { connection: 'keep-alive' })
  .then(json => { console.log('posted and got json:', json) })
  .catch(error => { console.log('posted and got error:', error) })

// Get from 'http://myCoolApi.com/', with 'same-origin' credentials,
//  custom errorParser and specific statusValidator
const statusValidator = (status) => status > 0 && status < 100

myAPISource.get('', {}, { statusValidator })
  .then(json => { console.log('got the json:', json) })
  .catch(error => { console.log('got an error:', error) })

Arguments

url / baseUrl / endPoint

• url: a string containing a full url i.e. https://api.github.com/user/repos
• baseUrl: a string containing a root api url i.e. https://api.github.com/user or https://api.github.com
• endPoint: a string containing an API endpoint i.e. repos or user/repos

fetchOptions

An object containing options for the request. Directly passed to fetch second argument. this is the place to set headers, body, and other request data. Example:

{
  method: 'post',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Hubot',
    login: 'hubot',
  }),
}

operationOptions

An object that modifies the operations default behavior. The following key/values are supported:

• dontParse Boolean: If true the response object will be passed as is. Useful when you need the response headers or metadata. Default is false.

  // Maybe you just need the headers
  get('http://myCoolApi.com/endpoint', {}, { dontParse: true })
    .then(response => console.log(response.headers))
  
  // Or maybe you also need the parsed body
  get('https://test/dontParse', {}, { dontParse: true })
    .then(response =>
      // response.json() returns a promise that resolves to the parsed body
      // so we need to return the result when that promise resolves
      Promise.all([response.headers, response.json()])
    )
    .then(([headers, json]) => console.log(headers.get('content-type'), json))
  

• statusValidator (response_status): A function that receives the response status code, implements some custom validation and returns true for valid statuses and false for invalid ones

  // A custom status validator that passes on status 0 to 100 and fails on everything else
  const statusValidator = (status) => status > 0 && status < 100
  
  // Use it!
  get('http://myCoolApi.com/endpoint', {}, { statusValidator })
    .then(json => { console.log('got the json:', json) })

• errorParser (error, response): A function that receives the parsed rejected response (error), the raw response object and returns an error response

  // A custom error parser that passes some custom data
  const errorParser = (error, response) => {
    const _error = new Error('Custom Error')
    _error.name = response.statusText
    _error.response = response
    _error.body = error
    _error.myExtraStuff = 'teach me how to dougie, teach me-teach me how to dougie~'
    return _error
  }
  
  // Use it!
  get('http://myCoolApi.com/endpoint', {}, { errorParser })
    .then(json => { console.log('got the json:', json) })
    .catch(error => { console.log('got an error:', error) })