api-operations

    1.3.0 • Public • Published

    API Operations

    Travis npm package Coveralls

    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

    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) })

    Install

    npm i api-operations

    DownloadsWeekly Downloads

    65

    Version

    1.3.0

    License

    MIT

    Last publish

    Collaborators

    • burabure