@dadi/api-wrapper

DADI API wrapper

A high-level library for interacting with DADI API

Overview

DADI API is a high performance RESTful API layer designed in support of API-first development and the principle of COPE.

This library provides a high-level abstraction of the REST architecture style, exposing a set of chainable methods that allow developers to compose complex read and write operations using a simplistic and natural syntax.

Getting started

1. Install the @dadi/api-wrapper module:

   npm install @dadi/api-wrapper --save
   

2. Add the library and configure the API settings:

   var DadiAPI = require('@dadi/api-wrapper')
   var api = new DadiAPI({
     uri: 'http://api.example.com',
     port: 80,
     credentials: {
       clientId: 'johndoe',
       secret: 'f00b4r'
     },
     version: 'vjoin',
     database: 'testdb'
   })
   

3. Make a query:

   // Example: getting all documents where `name` contains "john" and age is greater than 18
   api.in('users')
       .whereFieldContains('name', 'john')
       .whereFieldIsGreaterThan('age', 18)
       .find()
       .then(function (response) {
      	 // Use documents here
       })
   

Methods

Each query consists of a series of chained methods to form the request, always terminated by an operation method. There are 5 terminating operations that return a Promise with the result of one or more requests to the database: create(), delete(), find(), apply() and update().

These operations (with the exception of create()) can make use of a series of filtering methods to create the desired subset of documents to operate on.

Operations

.apply(callback)

Updates a list of documents with the result of individually applying callback to them.

api.in('users')
   .whereFieldExists('gender')
   .apply(function (document) {
      document.name = (document.gender === 'male') ? ('Mr ' + document.name) : ('Mrs ' + document.name)

      return document
   })

.create()

Creates a document.

// Example
api.in('users')
   .create({
      name: 'John Doe',
      age: 45,
      address: '123 Fake St'
   })
   .then(function (doc) {
      console.log('New document:', doc)
   })
   .catch(function (err) {
      console.log('! Error:', err)
   })

.delete()

Deletes one or more documents.

api.in('users')
   .whereFieldDoesNotExist('name')
   .delete()

.find(options)

Returns a list of documents.

api.in('users')
   .whereFieldIsGreaterThan('age', 21)
   .useFields(['name', 'age'])
   .find()

options is one of the following:

• extractResults (Boolean): Selects whether just the results array should be returned, rather than the entire API response.
• extractMetadata (Boolean): Selects whether just the metadata object should be returned, rather than the entire API response.

.getConfig()

Gets the config for a collection or for the API.

// Gets the collection config
api.in('users')
   .getConfig()

// Gets the API config
api.getConfig()

.getStats()

Gets collection stats.

api.in('users')
   .getStats()

.setConfig()

Sets the config for a collection or for the API.

// Sets the collection config
var collectionConfig = {}

api.in('users')
   .setConfig(collectionConfig)

// Sets the API config
var apiConfig = {}

api.setConfig(apiConfig)

.update(update)

Updates a list of documents.

api.in('users')
   .whereFieldIsLessThan('age', 18)
   .update({
      adult: false
   })

Filters

Filtering methods are used to create a subset of documents that will be affected by subsequent operation methods.

.goToPage(page)

Defines the page of documents to be used.

// Example
api.goToPage(3)

.limitTo(limit)

Defines a maximum number of documents to be retrieved.

// Example
api.limitTo(10)

.sortBy(field, order)

Selects a field to sort on and the sort direction. Order defaults to ascending (asc).

// Example
api.sortBy('age', 'desc')

.useFields(fields)

Selects the fields to be returned in the response. Accepts array format.

// Example
api.useFields(['name', 'age'])

.where(query)

Filters documents using a MongoDB query object or a Aggregation Pipeline array. The methods above are ultimately just syntatic sugar for where(). This method can be used for complex queries that require operations not implemented by any other method.

// Example
api.where({name: 'John Doe'})

.whereFieldBeginsWith(field, text)

Filters documents where field begins with text.

// Example
api.whereFieldBeginsWith('name', 'john')

.whereFieldContains(field, text)

Filters documents where field contains text.

// Example
api.whereFieldContains('name', 'john')

.whereFieldDoesNotContain(field, text)

Filters documents field does not contain text.

// Example
api.whereFieldDoesNotContain('name', 'john')

.whereFieldEndsWith(field, text)

Filters documents where field starts with text.

// Example
api.whereFieldEndsWith('name', 'john')

.whereFieldExists(field)

Filters documents that contain a field.

// Example
api.whereFieldExists('name')

.whereFieldDoesNotExist(field)

Filters documents that do not contain a field.

// Example
api.whereFieldDoesNotExist('address')

.whereFieldIsEqualTo(field, value)

Filters documents where field is equal to value.

// Example
api.whereFieldIsEqualTo('age', 53)

.whereFieldIsGreaterThan(field, value)

Filters documents where field is greater than value.

// Example
api.whereFieldIsGreaterThan('age', 18)

.whereFieldIsGreaterThanOrEqualTo(field, value)

Filters documents where field is greater than or equal to value.

// Example
api.whereFieldIsGreaterThanOrEqualTo('age', 19)

.whereFieldIsLessThan(field, value)

Filters documents where field is less than value.

// Example
api.whereFieldIsLessThan('age', 65)

.whereFieldIsLessThanOrEqualTo(field, value)

Filters documents where field is less than or equal to value.

// Example
api.whereFieldIsLessThanOrEqualTo('age', 64)

.whereFieldIsOneOf(field, matches)

Filters documents where the value of field is one of the elements of matches.

// Example
api.whereFieldIsOneOf('name', ['John', 'Jack', 'Peter'])

.whereFieldIsNotEqualTo(field, value)

Filters documents where field is not equal to value.

// Example
api.whereFieldIsEqualTo('age', 53)

.whereFieldIsNotOneOf(field, matches)

Filters documents where the value of field is not one of the elements of matches.

// Example
api.whereFieldIsNotOneOf('name', ['Mark', 'Nathan', 'David'])

.withComposition(value)

Defines whether nested documents should be resolved using composition. The default is to let API decide based on the queried collection's settings.

// Example
api.withComposition()
api.withComposition(true) // same as above
api.withComposition(false)

Other methods

.fromEndpoint(endpoint)

Selects a custom endpoint to use. Please note that unlike collections, custom endpoints do not have a standardised syntax, so it is up to the authors to make sure the endpoint complies with standard DADI API formats, or they will not function as expected.

// Example
api.fromEndpoint('custom-endpoint')

.in(collection)

Selects the collection to use.

// Example
api.in('users')

.useDatabase(database)

Selects the database to use. Overrides any database defined in the initialisation options, and is reset when called without arguments.

// Example
api.useDatabase('testdb')

.useVersion(version)

Selects the version to use. Overrides any version defined in the initialisation options, and is reset when called without arguments.

// Example
api.useVersion('1.0')

Debug mode

With debug mode, you'll be able to see exactly how the requests made to API look like. This functionality is enabled by setting a debug property in the config:

var DadiAPI = require('@dadi/api-wrapper')
var api = new DadiAPI({
  uri: 'http://api.example.com',
  port: 80,
  credentials: {
    clientId: 'johndoe',
    secret: 'f00b4r'
  },
  version: 'vjoin',
  database: 'testdb',
  debug: true
})

[@dadi/api-wrapper] Querying URI: http://api.example.com:80/vjoin/testdb/articles?count=0

Changelog

[1.4.0] - 2016-12-09

Changed

The core functionality of API Wrapper has been extracted to form a new module api-wrapper-core. The change allows the use of the API Wrapper functionality in the browser as well as within server-side applications.