@skypager/helpers-client v1.1.1

Skypager Client Helper

The Client Helper is used to provide a functional interface on top of an axios REST API Client.

The functional interface is intended to provide a more fluent system for interacting with a REST API, which hides the fact that we are interacting with an API over the network at all.

The client helper is automatically bundled with the Skypager Node Runtime as well as with the Skypager Web Runtime

Example Usage

// runtime.js
const runtime = require('@skypager/runtime')
const ClientHelper = require('@skypager/helpers-client')

runtime.onRegister('clients', () => {
  runtime.clients.register('sheets', () => require('./client.js'))
})

runtime.use(ClientHelper)

const sheetsClient = runtime.client('sheets')

In the above example, we're registering a sheets client helper and creating an instance of it.

This file might look something like:

export const interfaceMethods = [
  'listSheets',
  'showFullSheet',
  'showWorksheet',
  'showSheetMetadata',
]

export function listSheets(query = {}) {
  return this.client.get(`/sheets`, { query }).then(r => r.data)
}

export function showFullSheet(sheetKey, query = {}) {
  return this.client.get(`/sheets/${sheetKey}`, { query }).then(r => r.data)
}

export function showSheetMetadata(sheetKey, query = {}) {
  return this.client.get(`/sheets-meta/${sheetKey}`, { query }).then(r => r.data)
}

export function showWorksheet(sheetKey, worksheetKey, query = {}) {
  return this.client.get(`/sheets/${sheetKey}/worksheetKey`, { query }).then(r => r.data)
}

Using sheetsClient might look like:

const runtime = require('./runtime.js')

async function main() {
  const client = runtime.clients('sheets')
  const sheets = await client.listSheets() 
  const sheetInfo = await client.showSheetMetadata().then(response => response.info)
}

main()

In the above code block, you'll notice the client has no idea about the underlying REST API.

This is useful in a large application, as the application can be built against a standard interface for loading information and that implementation is free to change however it wants to so long as it maintains compatability. It is also useful if you wanted to, for example, buid a completely offline mock version to be used in testing.

Helper Specification

The following names refer to values exported from a client helper instance module.

• baseUrl or baseURL - defines the base url the axios client will talk to

• createClient - used to create the underlying client communication gateway, usually an instance of the axios adapter

• interfaceMethods the Client Helper can export an array of names for functions the client helper module exports.

  In the example above, we have showWorksheet, listSheets, and showSheetMetadata, each of which is a function. This function will be bound to the instance of the client helper.

Advanced Usage

Given the architecture of the Client Helper, it can be used to generate a completely functional interface for an API using something like a Swagger Specification.

const swagger = require('./swagger-definition.json')

const interfaceMethods = getOperationNames(swagger)

const interfaceFunctions = createFunctionsFrom(swagger) 

module.exports = Object.assign({
  { interfaceMethods },
  interfaceFunctions
})

function getOperationNames(swaggerDefinition) {
  // swagger definitions will have a bunch of requests defined,
  // each has a url, method, and parameters
  return listOfFunctionNamesFoundIn(swaggerDefinition)
}

function createFunctionsFrom(swaggerDefinition) {
  const objectOfFunctions = {}
  // for each request defined in swagger, use the url, parameters, and method
  // to construct a call to axios.  wrap that in a function, and return it 
  return objectOfFunctions
}