qsapi v1.1.0

QSAPI

Quasi-API - Hand sanitiser for your API

• Why?
• Usage
  • Fetch
  • Schema modelling
• Examples
  • Fetch examples
  • Schema mapping example
• API
  • Fetch.req(options)
  • Fetch.setup(config)
• TODO

Why?

Sometimes API's are bad. Sometimes they fail, Sometimes they don't. Your application shouldn't have to deal with intermittent API issues, It shouldn't have to deal with mismatched property types, or properties missing altogether.

Usage

import {Qsapi, Schema} from 'qsapi'
const {type, transform, initial} = Schema 

var schema = {
    ip: {
        [type]: 'String',
        [initial]: '127.0.0.1',
        [transform]: (ip) => {
            return Number(ip.replace('.',''))
        }
    }
}

var initialData = {
    ip: '127.0.0.1'
}

var qsapi = Qsapi({ 
    options: { 
        url: 'https://whatsmyip.azurewebsites.net/json',
        timeout: 2000,
        retryCount: 5 
    },
    schema,
    intiialData
})

Fetch

QSAPI presumes that the API being called is unstable and often unavailable. It will by default attempt to fetch the resource data 3 times before rejecting the original promise. This default can be configured during initialisation of the QSAPI call.

Using fetch, in its most basic form, all you need to supply is a url, everything else is handled by the default values.

Schema modelling

A schema can be provided to QSAPI to transform the result of the API call to the expected object. This can be used to make sure the data coming back from the API is uniform and consistant to what the UI is expecting.

Examples

Fetch examples

Basic example

Make a GET request to google.com, timeout after 1 second, don't retry.

import {Fetch} from 'qsapi'
var opts = {
    url: 'http://www.google.com',

    // timeout after 1 second
    timeout: 1000,

    // don't retry
    retry: false
}

var instance = Fetch.req(opts)
instance.then((res) => {

    console.log(res) 
})

Advanced example:

import {Fetch} from 'qsapi'

var retryCount = 3
var opts = {
    url: 'http://httpstat.us/500',
    timeout: 2000,
    retry: (req) => {
        console.log(`retry attempt #${retryCount - req.retryCount + 1} ${req.url}`)
    },
    retryCount,
}

var instance = Fetch.req(opts)

// on successful response
instance.then((res) => {
    console.log('Success!', res)
})

// once retryCount reaches 0 and 
instance.catch((err) => {
    console.log(`${opts.url} could not be fetched: ${err.code}`)
})

Schema mapping example

Think for a moment that you were dealing with an API that returned a list of products, and price:

var data = {
    products: [
        {
            id: 'product1',
            name: 'product 1',
            description: 'the first product',
            price: 55
        }, 
        {
            id: 'product2',
            name: 'product 2',
            description: 'the second product',
            price: '66.50'
        },
        {
            id: 'product3',
            name: 'product 3',
            price: '$11.00'
        }
    ]
}

The API response above is not great, we have inconsitant fields which is common with NoSQL based data stores, we also have inconsistant typing of the price field across products.

If we were dealing with this API in the front end logic of our application, we would need to add a lot of bulk and complexity to be evaluated at runtime just to make sure the properties exist, and they are the type that we are expecting. Not only does this bulk the application out, it makes it generally harder to read and scale for any developers being on-boarded.

Using QSAPI schema mapping, we can define a schema for how we want our data to be structured, and typed:

import Schema from 'qsapi'
const {parse, type, initial, transform} = Schema

var schema = {
    products: {
        id: {
            [type]: 'string'
        },

        name: {
            [type]: 'string'
        },

        description: {
            [initial]: 'N/a'
        },

        price: {
            [transform]: (price) => {
                return parseFloat(price.toString().replace('$', ''), 2).toFixed(2)
            }
        }
    }
}

Using the schema defined above, we can parse our data source:

// ...(continued from above)...

var mappedData = parse(data, schema)

/*
    mappedData.products:

    [
        { 
            id: 'product1',
            name: 'product 1',
            description: 'the first product',
            price: 55 
        },
        { 
            id: 'product2',
            name: 'product 2',
            description: 'the second product',
            price: 66.5 
        },
        { 
            id: 'product3',
            name: 'product 3',
            price: 11,
            description: 'N/a' 
        } 
    ]
*/

After the mapping has been applied, each field is consistant in type, and also has the same fields. description was added to product3, price was transformed from being mixed type in the data to a float in the mapped data

API

Qsapi(options, schema [, initialData])

Methods:

Fetch.req(options)

This is the main fetch function that returns a fetch instance (Promise)

QSAPI uses axios under the hood so any property supported by axios is also supported by QSAPI.

The options is an object that will accept the following:

Example:

import {Fetch} from 'qsapi'

var opts = {
    url: 'http://whatismyip.azurewebsites.net/json',

    // cache the response
    cache: true,

    // called if request fails, the existance of this function causes retrying to be enabled.
    retry: (request) => {
        console.log(`Failed to load ${opts.url}, retrying`)
    },

    // the expected response type
    responseType: 'json'
}

// define an on error function that show when we give up.
var onError = (err) => {
    if (err.retryCount === 0) {
        console.log(`failed to load ${err.url}, giving up`)
    }
}

// setup the request instance
var instance = Fetch.req(opts)
instance.then((res) => {

    // when we have a response - output to the terminal
    console.log(`received response from ${opts.url}`)

    // then make the request again
    Fetch.req(opts).then((res) => {

        // when we have the response again, check if it was pulled from the cache
        if (res.cached) {
            console.log(`loaded response from cache for ${opts.url}`)
        }
        else {
            console.log(`received response from ${opts.url}`)
        }
    })
    .catch(onError)
})
.catch(onError)

Fetch.setup(config)

This method will set up the fetch instance with a cache.

If you wish to use caching and want something a bit more elaborate than in-memory caching

Example:

import {Fetch} from 'qsapi'

var cacheStore = []

Fetch.setup({
    cache: {
        get: (key) => {
            // this will get called with the URL of the requested resources.
            // Must return a response.
            return cacheStore[key]
        },

        set: (key, value) => {
            // this will get called when the requested resource returns with a response.
            /*
                EG:
                key: 'http://www.google.com'
                value: {
                    data: {},
                    status: 200,
                    statusText: 'OK',
                    headers: {},
                    config: {}
                }
            */
            cacheStore[key] = value
        }
    }
})

Schema

Schema exports all of the symbols that we use to run specific logic on properties:

Schema.parse(data, model)

This will parse the data using the model supplied, a new object will be returned.

Schema.type

Define that the object should include this property and it should be a JavaScript type (Not implemented yet)

Schema.initial

The default value to use for a property.

Example:

var data = {
    products: [{
        id: 1,
        name: 'car'
        SKU: '123'
    }]
}

var schema = {
    products: [{
        id: {
            [type]: 'number'
        }

        name: {
            [type]: 'string'
        },

        SKU: {
            [rename]: 'sku'
        },

        description: {
            [initial]: 'One of our products'
        }
    }]
}

Once parsed, the new data object will contain a product with an id, name, sku and a description of 'One of our products'

Schema.transform

Transform the object using the data object as a property.

Example:

var data = {
    products: [{
        id: 1,
        sku: 'someSku1'
    }]
}

var schema = {
    products: [{
        id: {
            [type]: 'number'
        },

        sku: {
            [transform]: (sku) => {
                return sku.toUpperCase()
            }
        }
    }]
}

This will return an object with the products array, any obj in the product array that has a sku will be transformed toUpperCase()

Schema.custom

If you there is no property by the name of what you want on the object, you can generate one by using the [custom] Symbol.

Example:

var data = {
    products: [{
        id: 1,
        sku: 'someSku1'
    }]
}
var schema = {
    products: [{
        id: {
            [type]: 'number'
        },

        [custom]: (product) => {
            return {
                name: product.sku.toLowerCase().replace(/\d+/gi, '')
            }
        }
    }]
}

This will add a name property to the objects in the array.

Schema.required

If specific data is required, and the object is pointless without it, you can use the required property.

Example:

var data = {
    products: [{
        id: 1,
        name: 'a plant',
        sku: 'someSku1'
    }, {
        id: 2,
        sku: 'someSku2'
    }]
}
var schema = {
    products: [{
        id: {
            [type]: 'number'
        },

        name: {
            [required]: true
        }
    }]
}

This will make sure that any objects in the products array will contain a name, in the above example, the products array will contain 1 object.

TODO

• Schema mapping
• Schema type transformation
• Fetch API
• Fetch setup to allow for retries, timeouts, bailouts
• Pre-fetch caching
• Post-fetch caching