Anchor link Requirements

Microservices in the DADI platform are built on Node.js, a JavaScript runtime built on Google Chrome's V8 JavaScript engine. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient.

DADI follows the Node.js LTS (Long Term Support) release schedule, and as such the version of Node.js required to run DADI products is coupled to the version of Node.js currently in Active LTS. See the LTS schedule for further information.

Anchor link Creating an API

The easiest way to install API is using DADI CLI. CLI is a command line application that can be used to create and maintain installations of DADI products. Follow the simple instructions below, or see more detailed documentation for DADI CLI.

Anchor link Install DADI CLI

$ npm install @dadi/cli -g

Anchor link Create new API installation

There are two ways to create a new API with the CLI: either manually create a new directory for API or let CLI handle that for you. DADI CLI accepts an argument for project-name which it uses to create a directory for the installation.

Manual directory creation

$ mkdir my-api
$ cd my-api
$ dadi api new

Automatic directory creation

$ dadi api new my-api
$ cd my-api

DADI CLI will install the latest version of API and copy a set of files to your chosen directory so you can launch API almost immediately.

Installing DADI API directly from NPM

All DADI platform microservices are also available from NPM. To add API to an existing project as a dependency:

$ cd my-existing-node-app
$ npm install --save @dadi/api

Anchor link Application Anatomy

When CLI finishes creating your API, the application directory will contain the basic requirements for launching your API. The following directories and files have been created for you:

my-api/
  config/              # contains environment-specific configuration files
    config.development.json
  server.js            # the entry point for the application
  package.json
  workspace/
    collections/       # collection specification files
    endpoints/         # custom JavaScript endpoints

Anchor link Configuration

API reads a series of configuration parameters to define its behaviour and to adapt to each environment it runs on. These parameters are defined in JSON files placed inside the config/ directory, named as config.{ENVIRONMENT}.json, where {ENVIRONMENT} is the value of the NODE_ENV environment variable. In practice, this allows you to have different configuration parameters for when API is running in development, production and any staging, QA or anything in between, as per the requirements of your development workflow.

Some configuration parameters also have corresponding environment variables, which will override whatever value is set in the configuration file.

The following table shows a list of all the available configuration parameters.

String | search.database | The name of the database to use for storing and querying indexed documents | DB_SEARCH_NAME | search | String

Anchor link Authentication

DADI API provides a full-featured authentication layer based on the Client Credentials flow of oAuth 2.0. Consumers must exchange a set of client credentials for a temporary access token, which must be appended to API requests.

A client is represented as a set of credentials (ID + secret) and an access type, which can be set to admin or user. If set to admin, the client can perform any operation in API without any restrictions. If not, they will be subject to the rules set in the access control list.

Anchor link Adding clients

If you've installed DADI CLI you can use that to create a new client in the database. See instructions for Adding clients with CLI.

Alternatively, use the built in NPM script to start the Client Record Generator which will present you with a series of questions about the new client and insert a record into the configured database.

$ npm explore @dadi/api -- npm run create-client

Creating the client in the correct database

To ensure the correct database is used for your environment, add an environment variable to the command:

$ NODE_ENV=production npm explore @dadi/api -- npm run create-client

Anchor link Obtaining an access token

Obtain an access token by sending a POST request to your API's token endpoint, passing your client credentials in the body of the request. The token endpoint is configurable using the property auth.tokenRoute, with a default value of /token.

POST /token HTTP/1.1
Content-Type: application/json
Host: api.somedomain.tech
Connection: close
Content-Length: 65

{
  "clientId": "my-client-key",
  "secret": "my-client-secret"
}

With a request like the above, you should expect a response containing an access token, as below:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Content-Length: 95

{
  "accessToken": "4172bbf1-0890-41c7-b0db-477095a288b6",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "accessType": "admin"
}

Anchor link Using an access token

Once you have an access token, each request to the API should include an Authorization header containing the token:

GET /1.0/library/books HTTP/1.1
Content-Type: application/json
Authorization: Bearer 4172bbf1-0890-41c7-b0db-477095a288b6
Host: api.somedomain.tech
Connection: close

Anchor link Access token expiry

The response returned when requesting an access token contains a property expiresIn which is set to the number of seconds the access token is valid for. When this period has elapsed, API automatically invalidates the access token and a subsequent request to API using that access token will return an invalid token error.

The consumer application must request a new access token to continue communicating with the API.

Anchor link Internal collections

Internally, API uses three collections to store authentication data:

• clientStore: stores API clients
• roleStore: stores API roles
• accessStore: stores aggregate data computed from clients, roles and permissions

The names for these collections can be configured using the auth.clientCollection, auth.roleCollection and auth.accessCollection configuration properties, respectively. But unless they happen to clash with the name of one of your collections, you don't need to worry about setting them.

Anchor link Collection authentication

By default, collections require all requests to be authenticated and authorised. This behaviour can be changed on a per-collection basis by changing the authenticate property in the collection settings block, which can be set to:

The following configuration for a collection will allow all GET requests to proceed without authentication, while POST, PUT and DELETE requests will require authentication.

"settings": {
  "authenticate": ["POST", "PUT", "DELETE"]
}

See more information about collection specifications and their configuration.

Anchor link Authentication errors

API responds with HTTP 401 Unauthorized errors when either the supplied credentials are incorrect or an invalid token has been provided. The WWW-Authenticate header indicates the nature of the error. In the case of an expired access token, a new one should be requested.

Anchor link Invalid credentials

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer, error="invalid_credentials", error_description="Invalid credentials supplied"
Content-Type: application/json
content-length: 18
Date: Sun, 17 Sep 2017 17:44:48 GMT
Connection: close

Anchor link Invalid or expired token

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer, error="invalid_token", error_description="Invalid or expired access token"
Content-Type: application/json
content-length: 18
Date: Sun, 17 Sep 2017 17:46:28 GMT
Connection: close

Anchor link Access control

API includes a fully-fledged access control list (ACL) that makes it possible to specify in fine detail what each API client has permissions to do.

ACL terminology

The access control list specifies which clients can access the various resources of an API instance. Clients can have permissions assigned to them directly, or via roles, which can in their turn extend other roles.

Anchor link Resources

A resource is any entity in API that requires some level of authorisation to be accessed, like a collection or a custom endpoint. Resources are identified by a unique key with the following formats.

To specify what permissions someone has over a resource, an access matrix is used. It consists of an object that maps each of the CRUD methods (create, read, update and delete) to a value that determines whether that operation is allowed or not.

For example, the following matrices specify that on the library/book collection, the given client can read any document and update their own documents, whereas in the library/author collection they can create, read and update any documents, being limited to deleting only the documents they have created.

{
  "resources": {
    "collection:library_book": {
      "create": false,
      "delete": false,
      "deleteOwn": false,
      "read": true,
      "readOwn": false,
      "update": false,
      "updateOwn": true
    },
    "collection:library_author": {
      "create": true,
      "delete": false,
      "deleteOwn": true,
      "read": true,
      "readOwn": false,
      "update": true,
      "updateOwn": false
    }
  }
}

The table below shows all the CRUD methods supported.

Anchor link Advanced permissions for collection resources

When setting up the access matrix for a collection resource, it's possible to define finer-grained permissions that limit access to a subset of the fields or to documents that match a certain query.

To do this, the Boolean value that determines whether access is granted (true) or denied (false) gives way to an object that can contain one or both of the following properties:

• fields: Limits the fields that the client has access to. Uses the MongoDB projection format, meaning that fields can be included or excluded, but not both.

  Example:

    {
      "read": {
        "fields": {
          "title": 1,
          "author": 1
        }
      }
    }
  

• filter: Limits access to documents that match a given query. Supports any filtering operator.

  Example:

    {
      "read": {
        "filter": {
          "category": {
            "$in": ["art", "architecture"]
          }
        }
      }
    }
  

The following table shows how each of these properties is interpreted by the various access types.

Anchor link Resources API

The Resources API provides a read-only endpoint for listing all the registered resources.

                {
  "results": [
    {
      "name": "collection:library_book",
      "description": "library/book collection"
    }
  ]
}
              

Anchor link Clients

Clients represent users or applications that wish to interact with API. When not given administrator privileges (i.e. {"accessType": "admin"} in the database record), clients are subject to permissions defined in the access control list.

Anchor link Creating a client

The Clients API makes it possible to create a client using a RESTful endpoint, as long as the requesting client has create access to the clients resource or has administrator access.

Creating admin clients

For security reasons, it's not possible to create clients with administrator access via the Clients API. If you need to create one, see the manual method of adding a client, using either the DADI CLI or the create-client script.

Request

POST /api/clients HTTP/1.1
Content-Type: application/json
Authorization: Bearer c389340b-718f-4eed-8e8e-3400a1c6cd5a

{
  "clientId": "eduardo",
  "secret": "squirrel"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "results": [
    {
      "clientId": "eduardo",
      "accessType": "user",
      "resources": {},
      "roles": []
    }
  ]
}

The resources property in a client record shows the resources they have access to. By default, a client doesn't have access to anything until explicitly given the right permissions.

Let's see how we can give this client access to some resources.

Anchor link Assigning permissions

The Clients API includes a set of RESTful endpoints to manage the resources that a client has access to. The following request would give a client full permissions to access the library/book collection.

Request

POST /api/clients/eduardo/resources HTTP/1.1
Content-Type: application/json
Authorization: Bearer c389340b-718f-4eed-8e8e-3400a1c6cd5a

{
  "name": "collection:library_book",
  "access": {
    "create": true,
    "delete": true,
    "read": true,
    "update": true
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "results": [
    {
      "clientId": "eduardo",
      "accessType": "user",
      "resources": {
        "collection:library_book": {
          "create": true,
          "delete": true,
          "deleteOwn": false,
          "read": true,
          "readOwn": false,
          "update": true,
          "updateOwn": false       
        }
      },
      "roles": []
    }
  ]
}

At this point, eduardo can request an access token and access the library/book collection.

Anchor link Adding data to client records

The Clients API allows developers to associate arbitrary data with client records. This can be used by consumer applications to store data like personal information, user preferences or any type of metadata.

This data is stored in an object called data within the client record, and it can be written to when a client is created (via a POST request) or at any point afterwards via an update (PUT request). See the Clients API specification for more details.

When updating a client, the data object in the request body is processed as a partial update, which means the following in relation to any existing data object associated with the record:

1. New properties will be appended to the existing data object;
2. Properties with the same name as those in existing data object will be replaced;
3. Properties set to null will be removed from the data object.

Example 1 (creating a client with data):

POST /api/clients HTTP/1.1
Content-Type: application/json
Authorization: Bearer c389340b-718f-4eed-8e8e-3400a1c6cd5a

{
  "clientId": "eduardo",
  "secret": "sssshhh!",
  "data": {
    "firstName": "Eduardo"
  }
}

Example 2 (adding data to an existing client):

PUT /api/clients/eduardo HTTP/1.1
Content-Type: application/json
Authorization: Bearer c389340b-718f-4eed-8e8e-3400a1c6cd5a

{
  "data": {
    "lastName": "Boucas"
  }
}

Example 3 (removing a data property from a client):

PUT /api/clients/eduardo HTTP/1.1
Content-Type: application/json
Authorization: Bearer c389340b-718f-4eed-8e8e-3400a1c6cd5a

{
  "data": {
    "firstName": null
  }
}

Data properties prefixed with an underscore (e.g. _userId) can only be set and modified by admin clients, working as read-only properties for normal clients.

Anchor link Clients API

The Clients API provides a set of RESTful endpoints that allow the creation and management of clients, as well as granting and revoking access to resources and roles.

                {
  "results": [
    {
      "clientId": "eduardo",
      "accessType": "user"
    }
  ]
}
              

                {
  "results": [
    {
      "clientId": "eduardo",
      "accessType": "user",
      "resources": {
        "collection:library_book": {
          "create": true,
          "delete": false,
          "deleteOwn": true,
          "read": true,
          "readOwn": false,
          "update": false,
          "updateOwn": true
        }
      }
    }
  ]
}
              

                {
  "results": [
    {
      "clientId": "eduardo",
      "accessType": "user",
      "resources": {
        "collection:library_book": {
          "create": true,
          "delete": false,
          "deleteOwn": true,
          "read": true,
          "readOwn": false,
          "update": false,
          "updateOwn": true
        }
      }
    }
  ]
}
              

                {
  "results": [
    {
      "clientId": "eduardo",
      "accessType": "user",
      "resources": {
        "collection:library_book": {
          "create": true,
          "delete": false,
          "deleteOwn": true,
          "read": true,
          "readOwn": false,
          "update": false,
          "updateOwn": true
        }
      }
    }
  ]
}
              

                {
  "results": [
    {
      "clientId": "eduardo",
      "accessType": "user",
      "resources": {
        "collection:library_book": {
          "create": true,
          "delete": false,
          "deleteOwn": true,
          "read": true,
          "readOwn": false,
          "update": false,
          "updateOwn": true
        }
      }
    }
  ]
}
              

                {
  "results": [
    {
      "clientId": "eduardo",
      "accessType": "user",
      "resources": {
        "collection:library_book": {
          "create": true,
          "delete": false,
          "deleteOwn": true,
          "read": true,
          "readOwn": false,
          "update": false,
          "updateOwn": true
        }
      }
    }
  ]
}
              

                {
  "results": [
    {
      "clientId": "eduardo",
      "accessType": "user",
      "resources": {
        "collection:library_book": {
          "create": true,
          "delete": false,
          "deleteOwn": true,
          "read": true,
          "readOwn": false,
          "update": false,
          "updateOwn": true
        }
      },
      "roles": [
        "employee"
      ]
    }
  ]
}
              

                {
  "results": [
    {
      "clientId": "eduardo",
      "accessType": "user",
      "resources": {
        "collection:library_book": {
          "create": true,
          "delete": false,
          "deleteOwn": true,
          "read": true,
          "readOwn": false,
          "update": false,
          "updateOwn": true
        }
      }
    }
  ]
}
              

                {
  "results": [
    {
      "clientId": "eduardo",
      "accessType": "user",
      "resources": {
        "collection:library_book": {
          "create": true,
          "delete": false,
          "deleteOwn": true,
          "read": true,
          "readOwn": false,
          "update": false,
          "updateOwn": true
        }
      }
    }
  ]
}
              

Anchor link Roles

A role is a group of users that share a set of permissions to access a list of resources. In practice, it's an alternative way of giving permissions to clients.

For example, imagine that you wanted to give clients C1 and C2 a set of permissions to access resource R. You could either grant permissions to that resource individually to each client record, or you could grant the permissions to a role and assign it to both clients.

Anchor link Reconciling client and role permissions

A client may have their own resource permissions as well as permissions given by roles. Whenever a clash occurs, i.e. permissions for the same resource given directly and from a role, the access matrices are merged so that the broadest set of permissions is obtained.

For example, imagine that a client has the following access matrices for a given resource, one assigned directly and the other resulting from a role.

Matrix 1

{
  "create": false,
  "delete": true,
  "deleteOwn": false,
  "read": {
    "filter": {
      "fieldOne": "valueOne"
    }
  },
  "readOwn": false,
  "update": {
    "fields": {
      "fieldOne": 1
    }
  },
  "updateOwn": false
}

Matrix 2

{
  "create": true,
  "delete": false,
  "deleteOwn": true,
  "read": true,
  "readOwn": false,
  "update": {
    "fields": {
      "fieldTwo": 1,
      "fieldThree": 1
    }
  },
  "updateOwn": false
}

Resulting matrix

{
  "create": true,
  "delete": true,
  "deleteOwn": true,
  "read": true,
  "readOwn": false,
  "update": {
    "fields": {
      "fieldOne": 1,
      "fieldTwo": 1,
      "fieldThree": 1
    }
  },
  "updateOwn": false
}

Anchor link Extending roles

Roles can extend (or inherit from) other roles. If role R1 extends role R2, then clients with R1 will get the permissions granted by that role plus any permissions granted by R2. The inheritance chain can go on indefinitely.

Role inheritance is a good way to represent hierarchy typically present in organisations. For example, you could create a manager role that extends an employee role, since managers can usually do all the operations available to employees plus some of their own.

Anchor link Roles API

The Roles API provides a set of RESTful endpoints that allow the creation and management of roles, including granting and revoking access to resources.

                {
  "results": [
    {
      "name": "manager",
      "extends": "employee"
    }
  ]
}
              

                {
  "results": [
    {
      "name": "manager",
      "extends": "employee"
    }
  ]
}
              

                {
  "results": [
    {
      "name": "manager",
      "extends": "employee"
    }
  ]
}
              

                {
  "results": [
    {
      "name": "manager",
      "extends": "employee",
      "resources": {
        "collection:library_book": {
          "create": true,
          "delete": false,
          "deleteOwn": true,
          "read": true,
          "readOwn": false,
          "update": false,
          "updateOwn": true
        }
      }
    }
  ]
}
              

                {
  "results": [
    {
      "name": "manager",
      "extends": "employee",
      "resources": {
        "collection:library_book": {
          "create": true,
          "delete": false,
          "deleteOwn": true,
          "read": true,
          "readOwn": false,
          "update": false,
          "updateOwn": true
        }
      }
    }
  ]
}
              

Anchor link Using models directly

It's possible to tap into the access control list programmatically, which is useful when creating custom JavaScript endpoints or collection hooks. The ACL models allow you to create and modify clients and roles, as well as compute the permissions associated with a client and determine whether they can access a given resource.

The @dadi/api NPM module exports an ACL object with a series of public methods:

• access.get()
• client.create()
• client.delete()
• client.get()
• client.resourceAdd()
• client.resourceRemove()
• client.resourceUpdate()
• client.roleAdd()
• client.roleRemove()
• client.update()
• role.create()
• role.delete()
• role.get()
• role.resourceAdd()
• role.resourceRemove()
• role.resourceUpdate()
• role.update()

Anchor link access.get

Returns the access matrix representing the permissions of a given client to access a resource.

It expects the ID of the client as well as their access type, which means you may need to obtain this information with a separate query first. The reason for this is that the client ID + access type pair are encoded in the bearer token's JWT and are easily available via the req.dadiApiClient property.

Receives:

• client.clientId (type: String): ID of the client
• client.accessType (type: String): Access type of the client
• resource (type: String): ID of the resource
• resolveOwnTypes (type: Boolean, default: true): Whether to translate *Own types (e.g. readOwn) into a read property with a filter

Returns:

Promise<Object>: an object representing an access matrix.

Example:

const ACL = require('@dadi/api').ACL

ACL.access.get({
  clientId: 'restfulJohn',
  accessType: 'user'
}, 'collection:v1_foobar').then(access => {
  if (!access.read) {
    console.log('Client does not have `read` access!')
  }
})

Anchor link client.create

Creates a new client.

Note that all clients created using the ACL model have an access type of user. To create a client with an access type of admin, you must do so manually.

Receives (named parameters):

• clientId (type: String): ID of the client to create
• secret (type: String): The client secret

Returns:

Promise<Object>: an object representing the newly-created client.

Example:

const ACL = require('@dadi/api').ACL

ACL.client.create({
  clientId: 'restfulJohn',
  secret: 'superSecret!'
})

Anchor link client.delete

Deletes a client.

Receives:

• clientId (type: String): ID of the client to delete

Returns:

Promise with:

• {deletedCount, totalCount} (Object): Object indicating the number of clients that were deleted and the number of clients remaining after the operation

Example:

const ACL = require('@dadi/api').ACL

ACL.client.delete('restfulJohn')

Anchor link client.get

Returns a client by ID.

If secret is passed as a second argument, only a client that matches both the ID and the secret supplied will be retrieved.

Receives:

• clientId (type: String): ID of the client
• secret (type: String, optional): The client secret

Returns:

Promise<Object>: an object with a results property containing an array of matching clients.

Example:

const ACL = require('@dadi/api').ACL

ACL.client.get({
  clientId: 'restfulJohn',
  secret: 'superSecret!'
}).then(({results}) => {
  if (results.length === 0) {
    return console.log('Wrong credentials!')
  }

  console.log(results[0])
})

Anchor link client.resourceAdd

Gives a client permission to access a given resource.

Receives:

• clientId (type: String): ID of the client
• resource (type: String): ID of the resource
• access (type: Object): Access matrix

Returns:

Promise<Object>: the updated client.

Example:

const ACL = require('@dadi/api').ACL

ACL.client.resourceAdd(
  'restfulJohn',
  'collection:v1_things',
  {create: true, read: true}
)

Anchor link client.resourceRemove

Removes a client's permission to access a given resource.

Receives:

• clientId (type: String): ID of the client
• resource (type: String): ID of the resource

Returns:

Promise<Object>: the updated client.

Example:

const ACL = require('@dadi/api').ACL

ACL.client.resourceRemove(
  'restfulJohn',
  'collection:v1_things'
)

Anchor link client.resourceUpdate

Updates a client's permission to access a given resource.

Receives:

• clientId (type: String): ID of the client
• resource (type: String): ID of the resource
• access (type: Object): New access matrix

Returns:

Promise<Object>: the updated client.

Example:

const ACL = require('@dadi/api').ACL

ACL.client.resourceAdd(
  'restfulJohn',
  'collection:v1_things',
  {create: false, update: true}
)

Anchor link client.roleAdd

Assigns roles to a client.

Receives:

• clientId (type: String): ID of the client
• roles (type: Array<String>): Names of roles to assign

Returns:

Promise<Object>: the updated client.

Example:

const ACL = require('@dadi/api').ACL

ACL.client.roleAdd(
  'restfulJohn',
  ['operator', 'administrator']
)

Anchor link client.roleRemove

Unassigns roles from a client.

Receives:

• clientId (type: String): ID of the client
• roles (type: Array<String>): Names of roles to unassign

Returns:

Promise<Object>: the updated client.

Example:

const ACL = require('@dadi/api').ACL

ACL.client.roleRemove(
  'restfulJohn',
  ['operator', 'administrator']
)

Anchor link client.update

Updates a client.

Receives:

• clientId (type: String): ID of the client to update
• update (type: Object): The update object

Returns:

Promise<Object>: an object representing the updated client.

Example:

const ACL = require('@dadi/api').ACL

ACL.client.update(
  'restfulJohn',
  {secret: 'newSuperSecret!'}
})

Anchor link role.create

Creates a new role.

Receives (named parameters):

• name (type: String): Name of the role
• extends (type: String, optional): The name of a role to be extended

Returns:

Promise<Object>: an object representing the newly-created role.

Example:

const ACL = require('@dadi/api').ACL

ACL.role.create({
  name: 'administrator',
  extends: 'operator'
})

Anchor link role.delete

Deletes a role. If the role is extended by other roles, their extends property will be set to null.

Receives:

• name (type: String): Name of the role to be deleted

Returns:

Promise with:

• {deletedCount, totalCount} (Object): Object indicating the number of roles that were deleted and the number of roles remaining after the operation

Example:

const ACL = require('@dadi/api').ACL

ACL.role.delete('operator')

Anchor link role.get

Returns roles by name.

Receives:

• names (type: Array<String>): Names of the roles to retrieve

Returns:

Promise<Object>: an object with a results property containing an array of matching roles.

Example:

const ACL = require('@dadi/api').ACL

ACL.role.get(['operator', 'administrator'])

Anchor link role.resourceAdd

Gives a role permission to access a given resource.

Receives:

• role (type: String): Name of the role
• resource (type: String): ID of the resource
• access (type: Object): Access matrix

Returns:

Promise<Object>: the updated role.

Example:

const ACL = require('@dadi/api').ACL

ACL.role.resourceAdd(
  'operator',
  'collection:v1_things',
  {create: true, read: true}
)

Anchor link role.resourceRemove

Removes a role's permission to access a given resource.

Receives:

• role (type: String): Name of the role
• resource (type: String): ID of the resource

Returns:

Promise<Object>: the updated role.

Example:

const ACL = require('@dadi/api').ACL

ACL.role.resourceRemove(
  'operator',
  'collection:v1_things'
)

Anchor link role.resourceUpdate

Updates a role's permission to access a given resource.

Receives:

• role (type: String): Name of the role
• resource (type: String): ID of the resource
• access (type: Object): New access matrix

Returns:

Promise<Object>: the updated role.

Example:

const ACL = require('@dadi/api').ACL

ACL.role.resourceAdd(
  'operator',
  'collection:v1_things',
  {create: false, update: true}
)

Anchor link role.update

Updates a role.

Receives:

• role (type: String): Name of the role
• update (type: Object): The update object

Returns:

Promise<Object>: an object representing the updated role.

Example:

const ACL = require('@dadi/api').ACL

ACL.role.update(
  'superAdministrator',
  {extends: 'administrator'}
})

Anchor link Collections

A Collection represents data within your API. Collections can be thought of as the data models for your application and define how API connects to the underlying data store to store and retrieve data.

API can handle the creation of new collections or tables in the configured data store simply by creating collection specification files. To connect collections to existing data, simply name the file using the same name as the existing collection/table.

All that is required to connect to your data is a collection specification file, and once that is created API provides data access over a REST endpoint and programmatically via the API's Model module.

Anchor link Collections directory

Collection specifications are simply JSON files stored in your application's collections directory. The location of this directory is configurable using the configuration property paths.collections but defaults to workspace/collections. The structure of this directory is as follows:

my-api/
  workspace/
    collections/                    
      1.0/                          # API version
        library/                    # database
          collection.books.json     # collection specification file

API Version

Specific versions of your API are represented as sub-directories of the collections directory. Versioning of collections and endpoints acts as a formal contract between the API and its consumers.

Imagine a situation where a breaking change needs to be introduced — e.g. adding or removing a collection field, or changing the output format of an endpoint. A good way to handle this would be to introduce the new structure as version 2.0 and retain the old one as version 1.0, warning consumers of its deprecation and potentially giving them a window of time before the functionality is removed.

All requests to collection and custom endpoints must include the version in the URL, mimicking the hierarchy defined in the folder structure.

Database

Collection documents may be stored in separate databases in the underlying data store, represented by the name of the "database" directory.

Note This feature is disabled by default. To enable separate databases in your API the configuration setting database.enableCollectionDatabases must be true. See Collection-specific Databases for more information.

Collection specification file

A collection specification file is a JSON file containing at least one field specification and a configuration block.

The naming convention for collection specifications is collection.<collection name>.json where <collection name> is used as the name of the collection/table in the underlying data store.

Use the plural form

We recommend you use the plural form when naming collections in order to keep consistency across your API. Using the singular form means a GET request for a list of results can easily be confused with a request for a single entity.

For example, a collection named book (collection.book.json) will accept GET requests at the following endpoints:

https://api.somedomain.tech/1.0/library/book
https://api.somedomain.tech/1.0/library/book/560a44b33a4d7de29f168ce4

It's not obvious whether or not the first example is going to return all books, as intended. Using the plural form makes it clear what the endpoint's intended behaviour is:

https://api.somedomain.tech/1.0/library/books
https://api.somedomain.tech/1.0/library/books/560a44b33a4d7de29f168ce4

Anchor link The Collection Endpoint

API automatically generates a REST endpoint for each collection specification loaded from the collections directory. The format of the REST endpoint follows this convention /{version}/{database}/{collection name} and matches the structure of the collections directory.

my-api/
  workspace/
    collections/                    
      1.0/                          # API version
        library/                    # database
          collection.books.json     # collection specification file

With the above directory structure API will generate this REST endpoint: https://api.somedomain.tech/1.0/library/books.

Anchor link The JSON File

Collection specification files can be created and edited in any text editor, then added to the API's collections directory. API will load all valid collections when it boots.

Anchor link Minimum Requirements

The JSON file must contain a fields property and, optionally, a settings property.

• fields: must contain at least one field specification. See Collection Fields for the format of fields.
• settings: API uses sensible defaults for collection configuration, but these can be overridden using properties in the settings block. See Collection Settings for details.

A skeleton collection specification

{
  "fields": {
    "field1": {
    }
  },
  "settings": {
  }
}

Anchor link Collection Fields

Each field in a collection is defined using the following format. The only required property is type which tells API what data types the field can contain.

A basic field specification

"fieldName": {
  "type": "String"
}

A complete field specification

"fieldName": {
  "type": "String",
  "required": true,
  "label": "Title",
  "comments": "The title of the entry",
  "example": "War and Peace",
  "message": "must not be blank",
  "default": "Untitled"
  "matchType": "exact",
  "validation": {
    "minLength": 4,
    "maxLength": 20,
    "regex": {
      "pattern": "/[A-Za-z0-9]*/"
    }
  }
}

Anchor link Field Types

Every field in a collection must be one of the following types. All documents sent to API are validated against a collection's field type to ensure that data will be stored in the format intended. See the section on Validation for more details.

Anchor link Collection Settings

Each collection specification can contain a settings. API applies sensible defaults to collections, all of which can be overridden using properties in the settings block. Collection configuration is controlled in the following way:

{
  "settings": {
    "cache": true,
    "authenticate": true,
    "count": 100,
    "sort": "title",
    "sortOrder": 1,
    "callback": null,
    "storeRevisions": false
    "index": []
  }
}

Overriding configuration using querystring parameters

It is possible to override some of these values when requesting data from the endpoint, by using querystring parameters. See Querying a collection for detailed documentation.

Anchor link Collection configuration endpoints

Every collection in your API has an additional configuration route available. To use it, append /config to one of your collection endpoints, for example: https://api.somedomain.tech/1.0/libray/books/config.

Making a GET request to the collection's configuration endpoint returns the collection schema:

GET /1.0/library/books/config HTTP/1.1
Content-Type: application/json
Authorization: Bearer 37f9786b-3f39-4c87-a8ff-9530efd176c3
Host: api.somedomain.tech
Connection: close

HTTP/1.1 200 OK
Content-Type: application/json
content-length: 12639
Date: Mon, 18 Sep 2017 14:05:44 GMT
Connection: close

{
  "fields": {
    "published": {
      "type": "Object",
      "label": "Published State",
      "required": true
    }
  },
  "settings": {
  }
}

Anchor link The REST API

The primary way of interacting with DADI API is via REST endpoints that are automatically generated for each of the collections added to the application. Each REST endpoint allows you to insert, update, delete and query data stored in the underlying database.

Anchor link REST endpoint format

http(s)://api.somedomain.tech/{version}/{database}/{collection name}

The REST endpoints follow the above format, where {version} is the current version of the API collections (not the installed version of API), {database} is the database that holds the specified collection and {collection name} is the actual collection to interact with. See Collections directory for more detail.

Example endpoints for each of the supported HTTP verbs:

# Insert documents
POST /1.0/my-database/my-collection

# Update documents
PUT /1.0/my-database/my-collection

# Delete documents
DELETE /1.0/my-database/my-collection

# Get documents
GET /1.0/my-database/my-collection

Anchor link Content-type header

In almost all cases, the Content-Type header should be application/json. API contains some internal endpoints which allow text/plain but for all interaction using the above endpoints you should use application/json.

Anchor link Authorization header

Unless a collection has authentication disabled, every request using the above REST endpoints will require an Authorization header containing an access token. See Obtaining an Access Token for more detail.

Anchor link Working with data

Anchor link Retrieving data

Sending a request using the GET method instructs API to find and retrieve all documents that match a certain criteria.

There are two types of retrieval operation: one where a single document is to be retrieved and its identifier is known; and the other where one or many documents matching a query should be retrieved.

Anchor link Retrieve a single resource by ID

To retrieve a document with a known identifier, add the identifier to the REST endpoint for the collection.

Anchor link Request

Format: GET http://api.somedomain.tech/1.0/library/books/{ID}

GET /1.0/library/books/560a44b33a4d7de29f168ce4 HTTP/1.1
Authorization: Bearer afd4368e-f312-4b14-bd93-30f35a4b4814
Content-Type: application/json
Host: api.somedomain.tech

Retrieves the document with the identifier of {ID} from the specified collection (in this example books).

Anchor link Retrieve all documents matching a query

Useful for retrieving multiple documents that have a common property or share a pattern. Include the query in the querystring using the filter parameter.

Anchor link Request

Format: GET http://api.somedomain.tech/1.0/library/books?filter={QUERY}

GET /1.0/library/books?filter={"title":{"$regex":"the"}} HTTP/1.1
Authorization: Bearer afd4368e-f312-4b14-bd93-30f35a4b4814
Content-Type: application/json
Host: api.somedomain.tech

Anchor link Query options

When querying a collection, the following options can be supplied as URL parameters:

Anchor link Filtering documents

DADI API uses a MongoDB-style format for querying objects, introducing a series of operators that allow powerful queries to be assembled.

Anchor link Inserting data

Inserting data involves sending a POST request to the endpoint for the collection that will store the data. If the data passes validation rules imposed by the collection, it is inserted into the collection with a set of internal fields added.

Anchor link Request

Format: POST http://api.somedomain.tech/1.0/library/books

POST /1.0/library/books HTTP/1.1
Authorization: Bearer afd4368e-f312-4b14-bd93-30f35a4b4814
Content-Type: application/json
Host: api.somedomain.tech

{
  "title": "The Old Man and the Sea"
}

Anchor link Response

{
  "results": [
    "_id": "5ae1b6464e0b766dd17dbab9"
    "_apiVersion": "1.0",
    "_createdAt": 1511875141,
    "_createdBy": "your-client-id",
    "_version": 1,
    "title": "The Old Man and the Sea"
  ]
}

Anchor link Common validation errors

In addition to failures caused by validation rules in collection field specifications, you may also receive an HTTP 400 Bad Request error if either required fields are missing or extra fields are sent that don't exist in the collection:

HTTP/1.1 400 Bad Request
Content-Type: application/json
content-length: 681
Date: Mon, 18 Sep 2017 18:21:04 GMT
Connection: close

{
  "success": false,
  "errors": [
    {
      "field": "description",
      "message": "can't be blank"
    },
    {
      "field": "extra_field",
      "message": "doesn't exist in the collection schema"
    }
  ]
}

Anchor link Batch inserting documents

It is possible to insert multiple documents in a single POST request by sending an array to the endpoint:

POST /1.0/library/books HTTP/1.1
Authorization: Bearer afd4368e-f312-4b14-bd93-30f35a4b4814
Content-Type: application/json
Host: api.somedomain.tech

[
  {
    "title": "The Old Man and the Sea"
  },
  {
    "title": "For Whom the Bell Tolls"
  }
]

Anchor link Updating data

Updating data with API involves sending a PUT request to the endpoint for the collection that holds the data.

There are two types of update operation: one where a single document is to be updated and its identifier is known; and the other where one or many documents matching a query should be updated.

In both cases, the request body must contain the required update specified as JSON.

If the data passes validation rules imposed by the collection, it is updated using the specified update, and the internal fields _lastModifiedAt, _lastModifiedBy and _version are updated.

Anchor link Update an existing resource

To update a document with a known identifier, add the identifier to the REST endpoint for the collection.

Anchor link Request

Format: PUT http://api.somedomain.tech/1.0/library/books/{ID}

PUT /1.0/library/books/560a44b33a4d7de29f168ce4 HTTP/1.1
Authorization: Bearer afd4368e-f312-4b14-bd93-30f35a4b4814
Content-Type: application/json
Host: api.somedomain.tech

{
  "update": {
    "title": "For Whom the Bell Tolls (Kindle Edition)"
  }
}

Updates the document with the identifier of {ID} in the specified collection (in this example books). Applies the values from the update block specified in the request body.

Anchor link Response

{
  "results": [
    {
      "_apiVersion": "v1",
      "_createdAt": 1524741702962,
      "_createdBy": "testClient",
      "_history": [
        "5ae1b6c24e0b766dd17dbaba"
      ],
      "_id": "5ae1b6464e0b766dd17dbab9",
      "_lastModifiedAt": 1524741826339,
      "_lastModifiedBy": "testClient",
      "_version": 2,
      "title": "For Whom the Bell Tolls (Kindle Edition)"
    }
  ],
  "metadata": {
    "fields": {},
    "page": 1,
    "offset": 0,
    "totalCount": 1,
    "totalPages": 1
  }
}

Anchor link Update all documents matching a query

Useful for batch updating documents that have a common property. Include the query in the request body, along with the required update.

Anchor link Request

Format: PUT http://api.somedomain.tech/1.0/library/books

PUT /1.0/library/books HTTP/1.1
Authorization: Bearer afd4368e-f312-4b14-bd93-30f35a4b4814
Content-Type: application/json
Host: api.somedomain.tech

{
  "query": {
    "title": {
      "$regex": "the"
    }
  },
  "update": {
    "available": false
  }
}

Updates all documents that match the results of the query in the specified collection (in this example "books"). Applies the values from the update block specified in the request body.

Anchor link Response

{
  "results": [
    {
      "_apiVersion": "v1",
      "_createdAt": 1524741702962,
      "_createdBy": "testClient",
      "_history": [
        "5ae1b6c24e0b766dd17dbaba"
      ],
      "_id": "5ae1b6464e0b766dd17dbab9",
      "_lastModifiedAt": 1524741826339,
      "_lastModifiedBy": "testClient",
      "_version": 2,
      "title": "For Whom the Bell Tolls (Kindle Edition)",
      "available": false
    },
    {
      "_apiVersion": "v1",
      "_createdAt": 1524741702962,
      "_createdBy": "testClient",
      "_history": [
        "5ae1b6c24e0b766dd17dbaba"
      ],
      "_id": "5ae1b6464e0b766dd17dbab8",
      "_lastModifiedAt": 1524741826339,
      "_lastModifiedBy": "testClient",
      "_version": 1,
      "title": "The Old Man and the Sea",
      "available": false
    }
  ],
  "metadata": {
    "fields": {},
    "page": 1,
    "offset": 0,
    "totalCount": 2,
    "totalPages": 1
  }
}

Anchor link Deleting data

Sending a request using the DELETE method instructs API to perform a delete operation on the documents that match the supplied parameters.

There are two types of delete operation: one where a single document is to be deleted and its identifier is known; and the other where one or many documents matching a query should be deleted.

Anchor link Delete an existing resource

To delete a document with a known identifier, add the identifier to the REST endpoint for the collection.

Anchor link Request

Format: DELETE http://api.somedomain.tech/1.0/library/books/{ID}

DELETE /1.0/library/books/560a44b33a4d7de29f168ce4 HTTP/1.1
Authorization: Bearer afd4368e-f312-4b14-bd93-30f35a4b4814
Content-Type: application/json
Host: api.somedomain.tech

Deletes the document with the identifier of {ID} from the specified collection (in this example books).

Anchor link Delete all documents matching a query

Useful for batch deleting documents that have a common property. Include the query in the request body.

Anchor link Request

Format: DELETE http://api.somedomain.tech/1.0/library/books

DELETE /1.0/library/books HTTP/1.1
Authorization: Bearer afd4368e-f312-4b14-bd93-30f35a4b4814
Content-Type: application/json
Host: api.somedomain.tech

{
  "query": {
    "title": "The Old Man and the Sea"
  }
}

Deletes all documents that match the results of the query from the specified collection (in this example books).

Anchor link DELETE Response

The response returned for a DELETE request depends on the configuration setting for feedback.

The default setting is false, in which case API returns an HTTP 204 No Content after a successful delete operation.

If the setting is true – that is, the main configuration file contains "feedback": true – then a JSON object similar to the following is returned:

{
  "status": "success",
  "message": "Documents deleted successfully",
  "deletedCount": 1,
  "totalCount": 99
}

Where deletedCount is the number of documents deleted and totalCount the number of remaining documents in the collection.

In versions of API prior to 3.0, only the status and message fields are returned in the response.

Anchor link Using models directly

When creating custom JavaScript endpoints or collection hooks it may be useful to consume or create data, in which case it's possible to interact with the data model directly, as opposed to using the REST API, which would mean issuing an HTTP request.

The @dadi/api NPM module exports a factory function, named Model, which receives the name of the collection and returns a model instance with the following methods available.

• count()
• create()
• createIndex()
• delete()
• find()
• get()
• getIndexes()
• revisions()
• stats()
• update()

Note

API 3.1 introduced a new model API, using Promises instead of callbacks and a few other changes. The legacy version is still supported, but it is now deprecated and developers are encouraged to update their code.

Anchor link count

Searches for documents and returns a count.

Receives (named parameters):

• query (type: Object): Query to match documents against
• options (type: Object, optional): Options object for narrowing down the result set (e.g. {page: 3})

Returns:

Promise with:

• results (Object): Metadata block with document count

Example:

const Model = require('@dadi/api').Model

Model('books').count({
  query: {
    title: 'Harry Potter'
  }
}).then(results) => {
  console.log(results)
)

Anchor link create

Creates documents in the database. Runs any beforeCreate and afterCreate hooks configured in the collection.

Receives (named parameters):

• compose (type: Boolean, default: true): Whether to resolved referenced documents in the output payload
• documents (type: Object or Array): The document (object) or documents (array of objects) to create
• internals (type: Object, optional): A set of internal properties to add to each document (note: _id is generated automatically)
• callback (type: Function): Callback to process results
• rawOutput (type: Boolean, optional): By default, results suffer a series of transformations before being sent back to the consumer. The raw output can be obtained by setting this property to true
• req (type: Object, optional): The instance of http.IncomingMessage that originated the request

Returns:

Promise with:

• {results} (type: Object): Object with a results property containing an array of created documents

Example:

const Model = require('@dadi/api').Model

Model('books').create({
  documents: [
    { title: 'Harry Potter' },
    { title: 'Harry Potter 2' }
  ],
  internals: { _createdBy: 'johnDoe' },
  req
}).then(({results}) => {
  console.log(results)
})

Anchor link createIndex

Creates all the indexes defined in the settings.index property of the collection schema.

Receives:

N/A

Returns:

Promise with:

• indexes (type: Array): Array of indexes created, with each element being an object with a collection and index properties, which represent the name of the collection and the name of the field, respectively

Example:

const Model = require('@dadi/api').Model

Model('books').createIndex().then(indexes => {
  indexes.forEach(({collection, index}) => {
    console.log(`Created index ${index} in collection ${collection}.`)
  })
})

Anchor link delete

Deletes documents from the database. Runs any beforeDelete and afterDelete hooks configured in the collection.

Receives (named parameters):

• query (type: Object): Query to match documents against
• req (type: Object, optional): The instance of http.IncomingMessage that originated the request

Returns:

Promise with:

• {deletedCount, totalCount} (Object): Object indicating the number of documents that were deleted and the number of documents remaining in the collection after the operation

Example:

const Model = require('@dadi/api').Model

Model('books').delete({
  query: {
    title: 'Harry Potter'
  },
  req
}).then(({deletedCount, totalCount}) => {
  console.log(`Deleted ${deletedCount} documents, ${totalCount} remaining.`)
})

Anchor link find

Retrieves documents from the database.

Receives (named parameters):

• query (type: Object): Query to match documents against
• options (type: Object, optional): Options object for narrowing down the result set (e.g. {page: 3})

Returns:

Promise with:

• {metadata, results} (Object): Object representing the documents retrieved (results) as well as a metadata block indicating various types of metrics about the result set (metadata)

Example:

const Model = require('@dadi/api').Model

Model('books').find({
  options: {
    limit: 10,
    skip: 5
  }
  query: {
    title: 'Harry Potter'
  }
}).then(({metadata, results}) => {
  console.log(results)
})

Anchor link get

Retrieves documents from the database. Unlike find, it runs any beforeGet and afterGet hooks configured in the collection.

Receives (named parameters):

• query (type: Object): Query to match documents against
• options (type: Object, optional): Options object for narrowing down the result set (e.g. {page: 3})
• req (type: Object, optional): The instance of http.IncomingMessage that originated the request

Returns:

Promise with:

• {metadata, results} (Object): Object representing the documents retrieved (results) as well as a metadata block indicating various types of metrics about the result set (metadata)

Example:

const Model = require('@dadi/api').Model

Model('books').get({
  options: {
    limit: 10,
    skip: 5
  }
  query: {
    title: 'Harry Potter'
  },
  req
}).then(({metadata, results}) => {
  console.log(results)
})

Anchor link getIndexes

Retrieves all indexed fields.

Receives:

N/A

Returns:

Promise with:

• indexes (Array): An array of index objects, each with a name property

Example:

const Model = require('@dadi/api').Model

Model('books').getIndexes().then(indexes => {
  console.log(indexes)
})

Anchor link getRevisions

Retrieves revisions for a given document.

Receives (named parameters):

• id (type: String): ID of the document
• {historyFilters} (type: Object, optional): Object with a historyFilters property specifying a set of filters to match revision documents against

Returns:

Promise with:

• results (Array): The revision documents

Example:

const Model = require('@dadi/api').Model

Model('books').getRevisions({
  id: '560a44b33a4d7de29f168ce4'
}).then(results => {
  console.log(results)
})

Anchor link getStats

Retrieves statistics about a given collection.

Receives (named parameters):

• options (type: Object, optional): Options object for narrowing down the result set

Returns:

Promise with:

• stats (Object): Collection statistics

Example:

const Model = require('@dadi/api').Model

Model('books').getStats().then(stats => {
  console.log(stats)
})

Anchor link update

Updates documents in the database. Runs any beforeUpdate and afterUpdate hooks configured in the collection.

Receives (named parameters):

• compose (type: Boolean, default: true): Whether to resolved referenced documents in the output payload
• query (type: Object): Query to match documents against
• update (type: Object): Set of properties and values to update the documents affected by the query
• internals (type: Object): A set of internal properties to add to each document
• rawOutput (type: Boolean, default: false): By default, results suffer a series of transformations before being sent back to the consumer. The raw output can be obtained by setting this property to true
• req (type: Object, optional): The instance of http.IncomingMessage that originated the request

Returns:

Promise with:

• {results} (Object): Object with a results property containing the array of updated documents with their new state

Example:

const Model = require('@dadi/api').Model

Model('books').update({
  internals: {
    _lastModifiedBy: 'johnDoe'
  },
  query: {
    title: 'Harry Potter'
  },
  req,
  update: {
    author: 'J K Rowling'
  }
}).then(({results}) => {
  console.log(results)
})

Anchor link Validation

Documents sent to the API with POST and PUT requests are validated at field level based on rules defined in the collection schema.

Several means of data validation are supported in API, including type validation, mandatory field validation, length validation and regular expression validation.

While API can return default error messages when data fails validation, it is possible to customise the error messages for each field individually. See Error Messages below for more detail.

Anchor link Type Validation

A field can be validated by type. DADI API will check that the value supplied for the field is the correct type as specified in the schema. Only the following JavaScript primitives are considered for type validation: String, Number, Boolean.

"fields": {
  "title": {
    "type": "String",
    "message": "must be a string"
  }
}

Anchor link Mandatory Field Validation

Fields can be made mandatory by setting their required property to true. DADI API will check that a value has been supplied for the field when creating new documents. Validation for update requests is more relaxed and mandatory fields are not validated as they would have already been populated with data when the document was first created.

"fields": {
  "title": {
    "type": "String",
    "required": true
  }
}

Anchor link Length Validation

A field's length can be controlled by using the minLength and maxLength properties within the validation block. Validation will fail if the length of the string is greater or less than the specified length limits.

"fields": {
  "username": {
    "type": "String",
    "validation": {
      "maxLength": 16
    },
    "message": "is too long"
  },
  "password": {
    "type": "String",
    "validation": {
      "minLength": 6
    },
    "message": "is too short"
  }
}

Anchor link Regular Expression Validation

A regular expression pattern can be specified for a field, which may help enforcing business rules.

"fields": {
  "productCode": {
    "type": "String",
    "required": true,
    "validation": {
      "regex": {
        "pattern": "^A"
      }
    },
    "message": "must start with 'A'"
  }
}

Anchor link Validation Response

If a document fails validation an errors collection will be returned with the reasons for validation failure.

HTTP/1.1 400 Bad Request
Content-Type: application/json
content-length: 681
Date: Mon, 18 Sep 2017 18:21:04 GMT
Connection: close

{
  "success": false,
  "errors": [
    {
      "field": "title",
      "message": "must contain uppercase letters only"
    },
    {
      "field": "description",
      "message": "can't be blank"
    },
    {
      "field": "start_date",
      "message": "is invalid"
    },
    {
      "field": "extra_field",
      "message": "doesn't exist in the collection schema"
    }
  ]
}

Anchor link Error Messages

A set of default error messages are returned for fields that fail validation. The table below lists the built-in error messages and their associated meaning.

It is possible to supply a custom error message by specifying a message property in a field specification. For example:

"fields": {
  "title": {
    "type": "String",
    "required": true,
    "example": "The Autobiography of Benjamin Franklin",
    "message": "must contain a value"
  }
}

Anchor link Searching data

In versions 4.1 and above, DADI API ships with the ability to add search to your document collections. The data connector used must support searching with the inclusion of a search() method. Currently this is only supported by the MongoDB connector @dadi/api-mongodb.

Anchor link Configuration

A search block must be added to the configuration file:

"search": {
  "enabled": true,
  "minQueryLength": 3,
  "datastore": "@dadi/api-mongodb",
  "database": "search"
}

Anchor link Running a query

Query an indexed collection by adding /search to the collection's endpoint and include a q parameter in the querystring:

GET /1.0/library/books/search?q=wizard HTTP/1.1
Content-Type: application/json
Host: api.somedomain.tech

A response is returned in the same format as when performing any other GET query:

Response

{
  "results": [
    {
      "_apiVersion": "1.0",
      "_createdAt": 1532957892998,
      "_createdBy": "api-client",
      "_history": [],
      "_id": "5b5f14c4894d81942cb24aaf",
      "_version": 1,
      "title": "The Wizards of Once"
    },
    {
      "_apiVersion": "1.0",
      "_createdAt": 1532958892932,
      "_createdBy": "api-client",
      "_history": [],
      "_id": "5b5f14c4894d81942cb24aacd",
      "_version": 1,
      "title": "Off to Be the Wizard"
    }
  ],
  "metadata": {
    "search": "wizard",
    "limit": 40,
    "page": 1,
    "fields": {},
    "offset": 0,
    "totalCount": 2,
    "totalPages": 1
  }
}

Field filters can be applied in the same way as collection filtering:

GET /1.0/library/books/search?q=wizard&fields={"title": 1} HTTP/1.1
Content-Type: application/json
Host: api.somedomain.tech

Response

{
  "results": [
    {
      "_id": "5b5f14c4894d81942cb24aaf",
      "title": "The Wizards of Once"
    },
    {
      "_id": "5b5f14c4894d81942cb24aacd",
      "title": "Off to Be the Wizard"
    }
  ],
  "metadata": {
    "search": "wizard",
    "limit": 40,
    "page": 1,
    "fields": {
      "title": 1
    },
    "offset": 0,
    "totalCount": 2,
    "totalPages": 1
  }
}

Anchor link Indexing documents for search

To enable document indexing you must specify a search block for each field you'd like indexed within the collection schema, including the weight:

{
  "fields": {
    "title": {
      "type": "String",
      "label": "Title",
      "search": {
        "weight": 2
      }
    }
  }
}

Weight

This value is a multiplier applied to the final relevance index to boost a document's position in the results.

It allows a field to take further priority over other fields within a given document thus causing the document to return with a higher rank.

For example if two documents contain the word "banana", one in the title and the other in another field, if a weight of 2 has been applied to the title field, the document with "banana" in the title will receive a higher rank.

Anchor link Indexing all content

To start a background indexing process, send a POST request to the indexing endpoint. Ensure you have a valid bearer token in the Authorization header when making this request.

POST /api/index HTTP/1.1
Content-Type: application/json
Host: api.somedomain.tech
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJZCI6InRlc3QiLCJhY2Nlc3NUeXBlIjoiYWRtaW4iLCJpYXQiOjE1MzMwNTgwODMsImV4cCI6MTUzNDg1ODA4M30.xnM17sNEmVd1mO7azs0uVv1EIsVCX_rt6qCvyUtaf40

Anchor link Working with files

DADI API can easily be configured to accept file uploads, allowing you to store file-based content along with your text-based content.

API ships with a default media collection called mediaStore and a set of endpoints for generating signed URLs, uploading files and querying the media collection using the same functionality available for standard collections.

Anchor link Authentication

Media upload requests must be authenticated with a Bearer token supplied in an Authorization header along with the POST request. See the Authentication section for details on obtaining an access token.

Anchor link Configuration

There is a default global configuration for media uploads. To override the global configuration, add a media block to the main configuration file:

"media": {
  "storage": "disk",
  "basePath": "workspace/media",
  "pathFormat": "date",
  "tokenSecret": "d1ff1cult-w0nderland",
  "tokenExpiresIn": "1h"
}

Anchor link Available path formats

The pathFormat property determines the directory structure that API will use when storing files. This allows splitting files across many directories rather than storing them all in one directory. While this isn't a problem when using S3, when using the local filesystem storing a large number of files in one directory could negatively affect performance.

Anchor link Configuring media collections

To override the name of the default media collection, add a configuration property for defaultBucket:

"media": {
  "defaultBucket": "myDefaultMediaCollection"
}

To add additional media collections, add a buckets property:

"media": {
  "buckets": ["myImageCollection", "myFileCollection"]
}

Media collection endpoints

When interacting with the default media collection, endpoints begin with /media. When interacting with an additional media collection, endpoints begin with /media/<bucketName>, for example /media/myImageCollection

Anchor link Storage types

API ships with two file storage handlers, one for storing files on the local filesystem and the other for storing files in an S3-compatible service such as Amazon S3 or Digital Ocean Spaces. If you need access to the files from another application, for example DADI CDN, we recommend using the S3 option.

Anchor link File storage

The file storage handler saves uploaded files to the local filesystem, in the location specified by the basePath configuration property. basePath can be a path relative to the installation location of API or an absolute path.

"media": {
  "storage": "disk",
  "basePath": "workspace/media"
}

Anchor link S3-compatible storage

The S3-compatible storage handler allows API to interact with services such as Amazon S3 and Digital Ocean Spaces.

If the S3 storage handler is used, an additional set of configuration properties are required as seen in the s3 block below:

"media": {
  "storage": "s3",
  "basePath": "uploads",
  "pathFormat": "date",
  "s3": {
    "accessKey": "<your-access-key>",
    "secretKey": "<your-secret-key>",
    "bucketName": "<your-bucket>",
    "region": "eu-west-1"
  }
}

If using Digital Ocean Spaces, you'll require an additonal "s3.endpoint" property which should be set to something like "nyc3.digitaloceanspaces.com"

Security Note

We don't recommend storing your S3 credentials in the configuration file. The accessKey and secretKey properties should instead be set as the environment variables AWS_S3_ACCESS_KEY and AWS_S3_SECRET_KEY.

Anchor link Querying media collections

Media collections can be queried in the same way as regular API collections. Send a GET request to a media endpoint with a filter parameter:

GET /media/mediaStore?filter={"width": 150}

HTTP/1.1 200 OK
Content-Type: application/json
Connection: keep-alive

{
  "results": [
    {
      "_createdAt": 1525677293872,
      "_id": "5aeffceda32a4d53f24c8bd5",
      "_version": 1,
      "contentLength": 47237,
      "fileName": "10687215_10154599861380077_4088877300129205613_n.jpg",
      "height": 720,
      "mimetype": "image/jpeg",
      "path": "/media/2018/05/07/10687215_10154599861380077_4088877300129205613_n.jpg",
      "width": 960
    }
  ],
  "metadata": {
    "limit": 40,
    "page": 1,
    "fields": {},
    "offset": 0,
    "totalCount": 1,
    "totalPages": 1
  }

To include only certain properties in the returned response, supply a fields parameter:

GET /media/mediaStore?filter={"width": 150}&fields={"fileName": 1}

HTTP/1.1 200 OK
Content-Type: application/json
Connection: keep-alive

{
  "results": [
    {
      "_id": "5aeffceda32a4d53f24c8bd5",
      "fileName": "10687215_10154599861380077_4088877300129205613_n.jpg"
    }
  ],
  "metadata": {
    "limit": 40,
    "page": 1,
    "fields": {
      "fileName": 1
    },
    "offset": 0,
    "totalCount": 1,
    "totalPages": 1
  }

The file itself can be downloaded by sending a GET request for the value of the path property. For example, given the following media document, a GET request can be made to http://your-api-domain.com/media/2018/05/07/10687215_10154599861380077_4088877300129205613_n.jpg

{
  "_createdAt": 1525677293872,
  "_id": "5aeffceda32a4d53f24c8bd5",
  "_version": 1,
  "contentLength": 47237,
  "fileName": "10687215_10154599861380077_4088877300129205613_n.jpg",
  "height": 720,
  "mimetype": "image/jpeg",
  "path": "/media/2018/05/07/10687215_10154599861380077_4088877300129205613_n.jpg",
  "width": 960
}

Anchor link Uploading a file

To upload a file send a multipart/form-data POST to the media collection's endpoint. On successful upload the file's metadata is returned as JSON, and includes an identifier that can be used to create a reference to the file from another collection.

Anchor link Uploading a file with cURL

curl -X POST
  -H "Content-Type: multipart/form-data"
  -H "Authorization: Bearer 8df4a823-1e1e-4bc4-800c-97bb480ccbbe"
  -F "data=@/Users/userName/images/my-image.jpg" "http://api.somedomain.tech/media"

Anchor link Uploading a file with Node.js

const FormData = require('form-data')

let options = {
  host: 'api.somedomain.tech',
  port: 80,
  path: '/media',
  headers: {
    'Authorization': 'Bearer 8df4a823-1e1e-4bc4-800c-97bb480ccbbe',
    'Accept': 'application/json'
  }
}

let uploadResult = ''
let filePath = '/Users/userName/images/my-image.jpg'

let form = new FormData()
form.append('file', fs.createReadStream(filePath))

form.submit(options, (err, response, body) => {
  if (err) return reject(err)

  response.on('data', (chunk) => {
    if (chunk) {
      uploadResult += chunk
    }
  })

  response.on('end', () => {
    console.log(uploadResult)
  })
})

Anchor link Response

If successful, expect a response similar to the below examples.

Anchor link Disk storage

HTTP/1.1 201 Created
Content-Type: application/json
content-length: 305
Connection: keep-alive

{
  "results":[
    {
      "fileName": "my-image.jpg",
      "mimetype": "image/jpeg",
      "width": 1920,
      "height": 1080,
      "path": "/Users/userName/api/workspace/media/2016/12/19/my-image.jpg",
      "contentLength": 173685,
      "_createdAt": 1482124829485,
      "_createdBy": "your-client-key",
      "_version": 1,
      "_id": "58576e1d5dd9975624b0d92c"
    }
  ]
}

Anchor link S3 storage

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 305
Connection: keep-alive

{
  "results":[
    {
      "fileName": "my-image.jpg",
      "mimetype": "image/jpeg",
      "width": 1920,
      "height": 1080,
      "path": "workspace/media/2016/12/19/my-image.jpg",
      "contentLength": 173685,
      "_createdAt": 1482124902978,
      "_createdBy": "your-client-key",
      "_version": 1,
      "_id": "58576e72bafa53b625aebd4f"
    }
  ]
}

Anchor link Filename clashes

If using the filesystem storage and the filename of a file being uploaded is the same as an existing file, the new file will have its name changed by adding the current timestamp:

• Existing filename: my-image.jpg
• New filename: my-image-1480482847099.jpg

Anchor link Referencing files from another collection

Once a file is uploaded, its identifier can be used to create a reference from another collection. For this example we have a collection called books with the following schema:

{
  "fields": {
    "title": {
      "type": "String",
      "required": true
    },
    "content": {
      "type": "String",
      "required": true
    },
    "image": {
      "type": "Reference",
      "settings": {
        "collection": "mediaStore"
      }
    }
  },
  "settings": {
    "cache": true,
    "count": 40,
    "compose": true,
    "sort": "title",
    "sortOrder": 1
  }
}

The image field is a Reference field which will lookup the default mediaStore collection to resolve the reference. Having uploaded an image file and received its metadata, we can now send a POST to the books collection with the image identifier.

POST /1.0/library/books HTTP/1.1
Host: api.somedomain.tech
Content-Type: application/json
Authorization: Bearer 8df4a823-1e1e-4bc4-800c-97bb480ccbbe

{
  "title": "Harry Potter and the Philosopher's Stone",
  "content": "Harry Potter and the Philosopher's Stone is the first novel in the Harry Potter series and J. K. Rowling's debut novel, first published in 1997 by Bloomsbury.",
  "image": "58576e72bafa53b625aebd4f"
}

A subsequent GET request for this book would return a response such as:

{
  "title": "Harry Potter and the Philosopher's Stone",
  "content": "Harry Potter and the Philosopher's Stone is the first novel in the Harry Potter series and J. K. Rowling's debut novel, first published in 1997 by Bloomsbury.",
  "image": {
    "fileName":"my-image.jpg",
    "mimetype":"image/jpeg",
    "width":1920,
    "height":1080,
    "path":"workspace/media/2016/12/19/my-image.jpg",
    "contentLength":173685,
    "_createdAt":1482124902978,
    "_createdBy":"your-client-key",
    "_version":1,
    "_id":"58576e72bafa53b625aebd4f"
  }
}

Anchor link Pre-signed URLs

Pre-signed URLs are useful to allow your users or applications to be able to upload a file without requiring an access token. When you request a pre-signed URL, you must provide an access token (see Authentication) and specify an expected filename and MIME type for the file to be uploaded. The pre-signed URLs are valid only for the duration specified in the main configuration file or passed in the request for the signed URL.

Anchor link Configuration

"media": {
  "enabled": true,
  "tokenSecret": "catbus-goat-omelette",
  "tokenExpiresIn": "10h"
}

Anchor link Request a signed URL

To obtain a signed URL, send a POST request to the /media/sign endpoint. The body of the request should contain the filename and MIME type of the file to be uploaded:

POST /media/sign HTTP/1.1
Host: api.somedomain.tech
Content-Type: application/json
Authorization: Bearer 8df4a823-1e1e-4bc4-800c-97bb480ccbbe

{
  fileName: 'my-image.jpg',
  mimetype: 'image/jpeg'
}

API returns a response with a url property that contains the signed URL for uploading the specified file:

HTTP/1.1 200 OK
Content-Type: application/json
content-length: 305
Connection: keep-alive

{
  "url": "/media/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxlTmFtZSI6ImltYWdlLmpwZyIsImlhdCI6MTUyNzU3MzMzMiwiZXhwIjoxNTI3NTc2OTMyfQ.9d9HI3gCOSeuNgkeepISvs2QSvfcpXSSRBeHa6qVsXA"
}

Anchor link Override the expiry when requesting a signed URL

The globally-configured token expiry value can be overridden when requesting a signed URL by specifying a new expiry in the request to obtain the signed URL:

POST /media/sign HTTP/1.1

{
  fileName: 'my-image.jpg',
  mimetype: 'image/jpeg',
  expiresIn: '15000' // value in seconds
}

Anchor link Upload the file

With the signed URL obtained in the above step, a POST request can be sent to that URL with the file. See Uploading a file for information regarding the upload process.

POST /media/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxlTmFtZSI6ImltYWdlLmpwZyIsImlhdCI6MTUyNzU3MzMzMiwiZXhwIjoxNTI3NTc2OTMyfQ.9d9HI3gCOSeuNgkeepISvs2QSvfcpXSSRBeHa6qVsXA HTTP/1.1

Anchor link Deleting media

To delete, send a DELETE request to a media collection specifying a media document's _id property in the URL.

If successful, a 200 response is returned (or a 204 if feedback: false is set in configuration):

DELETE /media/5b10e5b76b600c760dc1cb93

{
  "status": "success",
  "message": "Document deleted successfully",
  "deleted": 1,
  "totalCount": 2
}

Anchor link Error messages

Anchor link Signed URL token expired

If the token for a signed URL has expired, the following response will be returned:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 305
Connection: keep-alive

{
  "statusCode": 400,
  "name": "TokenExpiredError",
  "message": "jwt expired",
  "expiredAt": "2018-05-29T05:59:17.000Z"
}

Anchor link Invalid filename

If the filename of the uploaded file doesn't match that sent in the request to obtain the signed URL, API returns a 400 error:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 305
Connection: keep-alive

{
  "statusCode": 400,
  "name": "Unexpected filename",
  "message": "Expected a file named 'my-image.jpg'"
}

Anchor link Invalid MIME type

If the MIME type of the uploaded file doesn't match that sent in the request sent to obtain the signed URL, API returns a 400 error:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 305
Connection: keep-alive

{
  "statusCode": 400,
  "name": "Unexpected mimetype",
  "message": "Expected a mimetype of 'image/jpeg'"
}

Anchor link Multiple languages

API supports multiple languages for documents with translations at a field level. Currently, fields of type String can be translatable.

Anchor link Configuration

By default, a single language is used by API. It can be configured via the i18n.defaultLanguage property, which takes an ISO-639-1 code, defaulting to en (English).

To support additional languages, add the ISO codes for the languages you wish to support to the i18n.languages configuration property, as an array. For example, to support French in Portuguese in addition to the default language, set i18n.languages to ['fr', 'pt'].

Example:

{
  "i18n": {
    "defaultLanguage": "en",
    "languages": ["fr", "pt"]
  }
}

Anchor link Creating multi-language documents

The name of a translated field is formed by concatenating the name of the raw field with the ISO code of the language, with a special character in the middle: {NAME}:{LANGUAGE CODE}. For example, title:pt is the Portuguese translation of the title field.

Note that the special character that glues the name of the field with the language code is configurable via the i18n.fieldCharacter property. The default is a colon (:).

To create a multi-language document, use the normal collection endpoints and specify a value for each of the fields you wish to translate.

POST /1.0/library/books HTTP/1.1
Authorization: Bearer afd4368e-f312-4b14-bd93-30f35a4b4814
Content-Type: application/json
Host: api.somedomain.tech

{
  "title": "The Little Prince",
  "title:pt": "O Principezinho",
  "title:fr": "Le Petit Prince",
  "author": "Antoine de Saint-Exupéry"
}

Unconfigured languages

Inserting a document with a translated field for a language that is not configured in i18n.languages will be accepted and will not throw a validation error, but those values will not be returned in queries. This allows languages to be worked on before they are ready for public consumption.

Anchor link Querying multi-language documents

Clients may request the version of one or multiple documents for a specific language using the lang URL parameter, which must contain an ISO-639-1 code. When present, API will attempt to find a translation to that language for each field in the documents collected by the query. When one is found, the translation is used as the field value, otherwise the original value is picked.

GET /1.0/library/books/58176e72bafa53b625aebd4f?lang=fr HTTP/1.1
Authorization: Bearer afd4368e-f312-4b14-bd93-30f35a4b4814
Content-Type: application/json
Host: api.somedomain.tech

{
  "_id": "58176e72bafa53b625aebd4f",
  "_i18n": {
    "title": "fr",
    "author": "en"
  },
  "title": "Le Petit Prince",
  "author": "Antoine de Saint-Exupéry"
}

When requesting a specific language, an _i18n object is added to the response, indicating which language was used for each of the translatable fields. In the example above, we requested the French version of a document and the title field had a French translation, so that was used and reflected on _i18n.title. The author field had no French version, so the original value was used and _i18n.author contains the ISO code of the default language.

When a lang parameter is not present, the raw content of documents is returned, containing the original value and all the language variations of each translatable field. In this case, no _i18n field is added to the documents.

GET /1.0/library/books/58176e72bafa53b625aebd4f HTTP/1.1
Authorization: Bearer afd4368e-f312-4b14-bd93-30f35a4b4814
Content-Type: application/json
Host: api.somedomain.tech

{
  "_id": "58176e72bafa53b625aebd4f",
  "title": "The Little Prince",
  "title:pt": "O Principezinho",
  "title:fr": "Le Petit Prince",
  "author": "Antoine de Saint-Exupéry"
}

Anchor link Languages endpoint

The languages endpoint allows authenticated users to obtain a list of all the languages supported by the API instance.

                {
  "results": [
    {
      "code": "pt",
      "name": "Portuguese",
      "local": "Português"
    }
  ],
  "metadata": {
    "defaultLanguage": {
      "code": "pt",
      "name": "Portuguese",
      "local": "Português"
    },
    "totalCount": 1
  }
}
              

Anchor link Creating Database Indexes

Indexes provide high performance read operations for frequently used queries and are fundamental in ensuring performance under load and at scale.

Database indexes can be automatically created for a collection by specifying the fields to be indexed in the settings block. An index will be created on the collection using the fields specified in the keys property.

An index block such as { "keys": { "fieldName": 1 } } will create an index for the field fieldName using an ascending order. The order will be reversed if the 1 is replaced with -1. Specifying multiple fields will create a compound index.

"settings": {
  "cache": true,
  "index": [
    {
      "keys": {
        "title": 1
      }
    }
  ]
}

Multiple indexes can be created for each collection, simply by adding more index blocks to the array for the index property.

Anchor link Index Options

Each index also accepts an options property. The options available for an index depend on the underlying data connector being used, so it's essential that you check the documentation for the data connector to determine what is possible. For example, the MongoDB data connector is capable of creating indexes with any of the options available in the MongoDB driver, such as specifying that an index be a unique index:

"index": [
  {
    "keys": {
      "email": 1
    },
    "options": {
      "unique": true
    }
  }
]

Anchor link Document Revision History

Anchor link settings.storeRevisions

If settings.storeRevisions is true:

• a revision collection will automatically be generated in the database when the first document for the collection is created
• a revision document will be stored in the revision collection when a new document is created
• a revision document will be stored for each subsequent update to an existing document
• each time a revision document is created, the _id of the revision document is pushed onto a _history array of the original document

Anchor link settings.revisionCollection

If settings.revisionCollection is specified, the collection's revision collection will be named according to the specified value, otherwise the collection's revision collection will take the form {collection name}History.

For example:

db.books.find()

Main document stored in the collection, with revisions referenced in the history array:

{
  "_id": "548efd7687fd8b50f3dca6e5",
  "title": "War and Peace",
  "_history": [
    "548efd7687fd8b50f3dca6e6",
    "548efd7687fd8b50f3dca6e7"
  ]
}

db.booksHistory.find()

Two revision documents stored in the revision collection — one created at the same time as the original document was created, the second created after an update operation to change the value of title:

{
  "_id": "548efd7687fd8b50f3dca6e6",
  "title": "Draft"
}

{
  "_id": "548efd7687fd8b50f3dca6e7",
  "title": "War and Peace",
  "_history": [
    "548efd7687fd8b50f3dca6e6"
  ]
}

Note: DADI API does not add or update any date/time fields to indicate the order in which revision documents were created, nor does it perform any sort operations when returning a document's revision history. It is up to the API consumer to include appropriate date/time fields and perform sort operations on the returned revision collection.

Anchor link Document Composition

To reduce data duplication caused by embedding sub-documents, DADI API allows the use of Reference fields which can best be described as pointers to other documents, which could be in the same collection, another collection in the same database or a collection in a different database.

Reference Field Settings

Anchor link A simple example

Consider the following two collections: books and people. books contains a Reference field author which is capable of loading documents from the people collection. By creating a book document and setting the author field to the _id value of a document from the people collection, API is able to resolve the reference and return the author as a subdocument within the response for a books query.

Books (collection.books.json)

{
  "fields": {
    "title": {
      "type": "String"
    },
    "author": {
      "type": "Reference",
      "settings": {
        "collection": "people"
      }
    }
  }
}

People (collection.people.json)

{
  "fields": {
    "name": {
      "type": "String"
    }
  }
}

Request

POST /1.0/library/books HTTP/1.1
Host: api.somedomain.tech
Authorization: Bearer 4172bbf1-0890-41c7-b0db-477095a288b6
Content-Type: application/json

{ "title": "For Whom The Bell Tolls", "author": "560a5baf320039f7d6a78d4a" }

Response

{
  "results": [
    {
      "_id": "560a5baf320039f1a3b68d4c",
      "_composed": {
        "author": "560a5baf320039f7d6a78d4a"
      },
      "author": {
        "_id": "560a5baf320039f7d6a78d4a",
        "name": "Ernest Hemingway"
      }
    }
  ]
}

Anchor link Enabling composition

Note

By default, referenced documents will not be resolved and the raw document IDs will be shown in the response. This is by design, since resolving documents adds additional load to the processing of a request and therefore it's important that developers actively enable it only when necessary.

Composition is the feature that allows API to resolve referenced documents before the response is delivered to the consumer. It means transforming document IDs into the actual content of the documents being referenced, and it can take place recursively for any number of levels – e.g. {"author": "X"} resolves to a document from the people collection, which in its turn may resolve {"country": "Y"} to a document from the countries collection, and so on.

API will resolve a referenced document for a particular level if the referenced collection has settings.compose: true in its schema file or if there is a compose URL parameter that overrides that behaviour.

The value of compose can be:

• false: Stops any referenced documents from being resolved
• true: Resolves all referenced documents for the current level; behaviour for nested levels depends on the value of settings.compose of the respective collections
• a number (e.g. compose=N): Resolves all referenced documents for N number of levels, including the current one
• all: Resolves all referenced documents for all levels

Anchor link The _composed property

When a document ID is resolved into a referenced document, the raw value of the Reference field is added to a _composed internal property. This allows consumers to determine that the result of a given field differs from its actual internal representation, which can still be accessed via the _composed property, if needed.

Anchor link Referencing one or multiple documents

Reference fields can link to one or multiple documents, depending on whether the input data is an ID or an array of IDs. The input format is respected in the composed response.

Request

POST /1.0/library/books HTTP/1.1
Host: api.somedomain.tech
Authorization: Bearer 4172bbf1-0890-41c7-b0db-477095a288b6
Content-Type: application/json

[
  { "title": "For Whom The Bell Tolls", "author": "560a5baf320039f7d6a78d4a" },
  { "title": "Nightfall", "author": [ "560a5baf320039f7d6a78d1a", "560a5baf320039f7d6a78d1a" ] }
]

Response

{
  "results": [
    {
      "_id": "560a5baf320039f1a3b68d4c",
      "_composed": {
        "author": "560a5baf320039f7d6a78d4a"
      },
      "title": "For Whom The Bell Tolls",
      "author": {
        "_id": "560a5baf320039f7d6a78d4a",
        "name": "Ernest Hemingway"
      }
    },
    {
      "_id": "560a5baf320039f1a3b68d4d",
      "_composed": {
        "author": [
          "560a5baf320039f7d6a78d1a",
          "560a5baf320039f7d6a78d1a" 
        ]
      }
      "title": "Nightfall",
      "author": [
        {
          "_id": "560a5baf320039f7d6a78d1a",
          "name": "Jake Halpern"
        },
        {
          "_id": "560a5baf320039f7d6a78d1b",
          "name": "Peter Kujawinski"
        }
      ]
    }
  ]
}

Anchor link Multi-collection references

Rather than referencing documents from a collection that is pre-defined in the settings.collection property of the field schema, a single field can reference documents from multiple collections. If the input data is an object (or array of objects) with a _collection and _data properties, then the corresponding values will be used to determine the collection and ID of each referenced document.

Movies (collection.movies.json)

{
  "fields": {
    "title": {
      "type": "String"
    },
    "crew": {
      "type": "Reference"
    }
  }
}

Directors (collection.directors.json), Producers (collection.producers.json) and Writers (collection.writers.json):

{
  "fields": {
    "name": {
      "type": "String"
    }
  }
}

Request

POST /1.0/library/movies HTTP/1.1
Host: api.somedomain.tech
Authorization: Bearer 4172bbf1-0890-41c7-b0db-477095a288b6
Content-Type: application/json

{
  "title": "Casablanca",
  "crew": [
    {
      "_collection": "writers",
      "_data": "5ac16b70bd0d9b7724b24a41"
    },
    {
      "_collection": "directors",
      "_data": "5ac16b70bd0d9b7724b24a42"
    },
    {
      "_collection": "producers",
      "_data": "5ac16b70bd0d9b7724b24a43"
    }
  ]
}

Response

{
  "results": [
    {
      "_id": "560a5baf320039f1a1b68d4c",
      "_composed": {
        "crew": [
          "5ac16b70bd0d9b7724b24a41",
          "5ac16b70bd0d9b7724b24a42",
          "5ac16b70bd0d9b7724b24a43"
        ]
      },
      "_refCrew": {
        "5ac16b70bd0d9b7724b24a41": "writers",
        "5ac16b70bd0d9b7724b24a42": "directors",
        "5ac16b70bd0d9b7724b24a43": "producers"
      },
      "title": "Casablanca",
      "crew": [
        {
          "_id": "5ac16b70bd0d9b7724b24a41",
          "name": "Julius J. Epstein"
        },
        {
          "_id": "5ac16b70bd0d9b7724b24a42",
          "name": "Michael Curtiz"
        },
        {
          "_id": "5ac16b70bd0d9b7724b24a43",
          "name": "Hal B. Wallis"
        }
      ]
    }
}

Note the presence of _refCrew in the response. This is an internal field that maps document IDs to the names of the collections they belong to, as that information is not possible to extract from the resolved documents.

Anchor link Strict composition

When API composes a set of documents, it ignores any IDs that do not match a valid document and also removes duplicate IDs from the response, returning a single instance of the repeated document. For example:

Request

POST /1.0/library/movies HTTP/1.1
Host: api.somedomain.tech
Authorization: Bearer 4172bbf1-0890-41c7-b0db-477095a288b6
Content-Type: application/json

{
  "title": "Inception",
  "cast": [
    "5ac16b70bd0d9b7724b24a41", // ID does not exist
    "5ac16b70bd0d9b7724b24a42",
    "5ac16b70bd0d9b7724b24a42", // Duplicate ID
    "5ac16b70bd0d9b7724b24a43"
  ]
}

Response

{
  "results": [
    {
      "_id": "560a5baf320039f1a1b68d4c",
      "_composed": {
        "cast": [
          "5ac16b70bd0d9b7724b24a41",
          "5ac16b70bd0d9b7724b24a42",
          "5ac16b70bd0d9b7724b24a42",
          "5ac16b70bd0d9b7724b24a43"
        ]
      },
      "title": "Inception",
      "cast": [
        {
          "_id": "5ac16b70bd0d9b7724b24a42",
          "name": "Leonardo DiCaprio"
        },
        {
          "_id": "5ac16b70bd0d9b7724b24a43",
          "name": "Ellen Page"
        }
      ]
    }
}

This behaviour can be changed by setting {"strictCompose": true} in the settings block of the Reference field. This tells API to produce an exact mapping of the input object, leaving null in the place of document IDs that do not match any documents, and resolving duplicate IDs multiple times. Here's how the response for the request above would look like if cast had strict composition enabled.

Response

{
  "results": [
    {
      "_id": "560a5baf320039f1a1b68d4c",
      "_composed": {
        "cast": [
          "5ac16b70bd0d9b7724b24a41",
          "5ac16b70bd0d9b7724b24a42",
          "5ac16b70bd0d9b7724b24a42",
          "5ac16b70bd0d9b7724b24a43"
        ]
      },
      "title": "Inception",
      "cast": [
        null,
        {
          "_id": "5ac16b70bd0d9b7724b24a42",
          "name": "Leonardo DiCaprio"
        },
        {
          "_id": "5ac16b70bd0d9b7724b24a42",
          "name": "Leonardo DiCaprio"
        },
        {
          "_id": "5ac16b70bd0d9b7724b24a43",
          "name": "Ellen Page"
        }
      ]
    }
}

Anchor link Pre-composed documents

Setting the content of a Reference field to one or multiple document IDs is the simplest way of referencing documents, but it creates some complexity for consumer apps that wish to insert multiple levels of referenced documents.

For example, imagine that you want to create a book and its author. You would:

1. Create the author document
2. Grab the document ID from step 1 and add it to the author property of a new book
3. Create the book document

You can see how this would get increasingly complex if you wanted to insert more levels. To address that, and as an alternative to receiving just document IDs, API is capable of processing a pre-composed set of documents and figure out what to do with the data, including creating and updating documents, as well as populating Reference fields with the right document IDs.

Anchor link Creating documents

When the content of a Reference field is an object without an ID, a corresponding document is created in the collection defined by the settings.collection property of the field schema. If an array is sent, multiple documents will be created.

Request

POST /1.0/library/books HTTP/1.1
Host: api.somedomain.tech
Authorization: Bearer 4172bbf1-0890-41c7-b0db-477095a288b6
Content-Type: application/json

[
  {
    "title": "For Whom The Bell Tolls",
    "author": { "name": "Ernest Hemingway" }
  },
  {
    "title": "Nightfall",
    "author": [
      { "name": "Jake Halpern" },
      { "name": "Peter Kujawinski" }
    ]
  }
]

Response

{
  "results": [
    {
      "_id": "560a5baf320039f1a3b68d4c",
      "_composed": {
        "author": "560a5baf320039f7d6a78d4a"
      },
      "title": "For Whom The Bell Tolls",
      "author": {
        "_id": "560a5baf320039f7d6a78d4a",
        "name": "Ernest Hemingway"
      }
    },
    {
      "_id": "560a5baf320039f1a3b68d4d",
      "_composed": {
        "author": [
          "560a5baf320039f7d6a78d1a",
          "560a5baf320039f7d6a78d1b"
        ]
      },
      "title": "Nightfall",
      "author": [
        {
          "_id": "560a5baf320039f7d6a78d1a",
          "name": "Jake Halpern"
        },
        {
          "_id": "560a5baf320039f7d6a78d1b",
          "name": "Peter Kujawinski"
        }
      ]
    }
  ]
}

Anchor link Updating documents

When the content of a Reference field is an object with an ID, API updates the document referenced by that ID with the new sub-document.

The example below creates a new book and sets an existing document (560a5baf320039f7d6a78d4a) as its author, but it also makes an update to the referenced document – in this case, name is changed to "Ernest Miller Hemingway".

Request

POST /1.0/library/books HTTP/1.1
Host: api.somedomain.tech
Authorization: Bearer 4172bbf1-0890-41c7-b0db-477095a288b6
Content-Type: application/json

[
  {
    "title": "For Whom The Bell Tolls",
    "author": {
      "_id": "560a5baf320039f7d6a78d4a",
      "name": "Ernest Miller Hemingway"
    }
  }
]

Response

{
  "results": [
    {
      "_id": "560a5baf320039f1a3b68d4c",
      "_composed": {
        "author": "560a5baf320039f7d6a78d4a"
      },
      "title": "For Whom The Bell Tolls",
      "author": {
        "_id": "560a5baf320039f7d6a78d4a",
        "name": "Ernest Miller Hemingway"
      }
    }
  ]
}

Anchor link Multi-collection references

It's possible to insert pre-composed documents that use the multi-collection reference syntax, as long as the pre-composed documents are inside the _data property of the outermost object in the Reference field value.

The example below shows how the various scenarios can be mixed and matched: the first element of crew is a new document to be created in the writers collection (no ID); the second item is a document ID, which will be stored as is in the directors collection; the third item references an existing document from the producers collection, whose name will be updated to a new value.

Request

POST /1.0/library/movies HTTP/1.1
Host: api.somedomain.tech
Authorization: Bearer 4172bbf1-0890-41c7-b0db-477095a288b6
Content-Type: application/json

{
  "title": "Casablanca",
  "crew": [
    {
      "_collection": "writers",
      "_data": {
        "name": "Julius J. Epstein"
      }
    },
    {
      "_collection": "directors",
      "_data": "5ac16b70bd0d9b7724b24a42"
    },
    {
      "_collection": "producers",
      "_data": {
        "_id": "5ac16b70bd0d9b7724b24a43",
        "name": "Hal Brent Wallis"
      }
    }
  ]
}

Response

{
  "results": [
    {
      "_id": "560a5baf320039f1a1b68d4c",
      "_composed": {
        "crew": [
          "5ac16b70bd0d9b7724b24a41",
          "5ac16b70bd0d9b7724b24a42",
          "5ac16b70bd0d9b7724b24a43"
        ]
      },
      "_refCrew": {
        "5ac16b70bd0d9b7724b24a41": "writers",
        "5ac16b70bd0d9b7724b24a42": "directors",
        "5ac16b70bd0d9b7724b24a43": "producers"
      },
      "title": "Casablanca",
      "crew": [
        {
          "_id": "5ac16b70bd0d9b7724b24a41",
          "name": "Julius J. Epstein"
        },
        {
          "_id": "5ac16b70bd0d9b7724b24a42",
          "name": "Michael Curtiz"
        },
        {
          "_id": "5ac16b70bd0d9b7724b24a43",
          "name": "Hal Brent Wallis"
        }
      ]
    }
  ]
}

Anchor link Limiting fields of referenced documents

When a reference is resolved, the entire referenced document will be included by default, but it's possible to limit the fields that will be included in the composed response. You can do this by specifying a fields array within the settings block of the Reference field's schema.

Books (collection.books.json)

{
  "fields": {
    "title": {
      "type": "String"
    },
    "author": {
      "type": "Reference",
      "settings": {
        "collection": "people",
        "fields": ["firstName", "lastName"]
      }
    }
  }
}

Alternatively, you can specify the fields to be retrieved for each Reference field using the fields URL parameter with dot-notation. The following request instructs API to get all books, limiting the fields returned to title and author, with the latter only showing the fields name and occupation from the referenced collection.

GET /1.0/library/books?fields={"title":1,"author.name":1,"author.occupation":1} HTTP/1.1
Host: api.somedomain.tech
Authorization: Bearer 4172bbf1-0890-41c7-b0db-477095a288b6
Content-Type: application/json

Anchor link Collection Statistics

Collection statistics can be retrieved by sending a GET request to a collection's /stats endpoint:

GET /1.0/library/books/stats HTTP/1.1
Host: api.somedomain.tech
Content-Type: application/json
Cache-Control: no-cache

An example response when using the MongoDB data connector:

{
  "count": 2,
  "size": 480,
  "averageObjectSize": 240,
  "storageSize": 8192,
  "indexes": 1,
  "totalIndexSize": 8176,
  "indexSizes": { "_id_": 8176 }
}

Anchor link Adding application logic

Anchor link Endpoints

DADI API custom endpoints give you the ability to modify, enrich and massage your data before it is returned to the user making the request. Collection endpoints return raw data in response to requests, whereas custom endpoints give you more control over what you return.

Anchor link Endpoint Specification

Endpoint specifications are simply JavaScript files stored in your application's /workspace/endpoints folder. It is important to understand how the folder hierarchy in the endpoints folder affects the behaviour of your API.

my-api/
  workspace/
    collections/                    # MongoDB collection specifications
      1.0/                          # API version label
    endpoints/                      # Custom Javascript endpoints
      1.0/                          # API version label

Anchor link Endpoint

Endpoint specifications exist as JavaScript files within a version folder as mentioned above. The naming convention for the collection specifications is endpoint.<endpoint name>.js

Anchor link Endpoint URL

With the above folder and file hierarchy an endpoint's URL uses the following format:

https://api.somedomain.tech/{version}/{endpoint name}

In actual use this might look like the following:

https://api.somedomain.tech/1.0/booksByAuthor

Anchor link The Endpoint file

Endpoint specification files should export functions with lowercase names that correspond to the HTTP method that the function is designed to handle.

For example:

module.exports.get = function (req, res, next) {

}

module.exports.post = function (req, res, next) {

}

Each function receives the following three arguments:

(request, response, next)

1. request is an instance of Node's http.IncomingMessage
2. response is an instance of Node's http.ServerResponse
3. next is a function that can be passed an error or called if this endpoint has nothing to do. Passing an error, e.g. next(err) will result in an HTTP 500 response. Calling next() will respond with an HTTP 404.

Example, HTTP 200 response

module.exports.get = function (req, res, next) {
  let data = {
    results: [
      {
        title: 'Book One',
        author: 'Benjamin Franklin'
      }
    ]
  }

  res.setHeader('content-type', 'application/json')
  res.statusCode = 200
  res.end(JSON.stringify(data))
}

Example, HTTP 404 response

module.exports.get = function (req, res, next) {
  res.setHeader('content-type', 'application/json')
  res.statusCode = 404
  res.end()
}

Example, HTTP 500 response

module.exports.get = function (req, res, next) {
  let error = {
    errors: [
      'An error occured while processing your request'
    ]
  }

  res.setHeader('content-type', 'application/json')
  res.statusCode = 500
  res.end(JSON.stringify(error))
}

Anchor link Custom Endpoint Routing

It is possible to override the default endpoint route by including a config function in the endpoint file. The function should return a config object with a route property. The value of this property will be used for the endpoint's route.

The following example returns a config object with a route that specifies an optional request parameter, id.

module.exports.config = function () {
  return {
    route: '/1.0/books/:id([a-fA-F0-9]{24})?'
  }
}

This route will now respond to requests such as

https://api.somedomain.tech/1.0/books/55bb8f688d76f74b1303a137

Without this custom route, the same could be achieved by requesting the default route with a querystring parameter.

https://api.somedomain.tech/1.0/books?id=55bb8f688d76f74b1303a137

Anchor link Authentication

Authentication can be bypassed for your custom endpoint by adding the following to your endpoint file:

module.exports.model = {}
module.exports.model.settings = { authenticate : false }

Anchor link Hooks

Hooks perform operations on data before/after GET, UPDATE and DELETE requests. In essence, a hook is simply a function that intercepts a document/query before it's executed, having the option to modify it before returning it back to the model.

Anchor link Use cases

• Creating variations of a field, such as creating a slug (example above);
• Validating fields with complex conditions, when a regular expression might not be enough;
• Triggering an action, notification or external command when a record is modified.

Anchor link Anatomy of a hook

A hook is stored as an individual file in a hooks directory (defaulting to /workspace/hooks) and can be used by being attached to create, update or delete operations in the settings section of a collection schema specification.

collections.user.json:

"settings": {
  "hooks": {
    "create": ["myhook1", "myhook2"]
  }
}

This means that whenever a new user is created, the document that is about to be inserted will be passed to myhook1, its return value will then be passed on to myhook2 and so on. After all the hooks finish executing, the final document will be returned to the model to be inserted in the database.

The order in which hooks are executed is defined by the order of the items in the array.

The following example defines a very simple hook, which will change the name field of a document before returning it.

module.exports = function (doc, type, data) {
  doc.name = 'Modified by the hook'

  return doc
}

This particular hook will receive a document, change a property (name) and return it back. So if attached to the create event, it will make all the created documents have name set to Modified by the hook.

However, this logic ties the hook to the schema — what happens if we want to modify a property other than name? Hooks are supposed to be able to add functionality to a document, and should be approached as interchangeable building blocks rather than pieces of functionality tightly coupled with a schema.

For that reason, developers might have the need to pass extra information to the hook — e.g. inform the hook the name of the properties that should be modified. As such, in addition to the syntax shown above for declaring a hook (an array of strings), an alternative one allows data to be passed through a options object.

"settings": {
  "hooks": {
    "beforeCreate": [
      {
        "hook": "slugify",
        "options": {
          "from": "title",
          "to": "slug"
        }
      }
    ]
  }
}

In this example we implement a hook that populates a field (slug) with a URL-friendly version of another field (title). The hook is created in such a way that the properties it reads from and writes to are dynamic, passed through as from and to from the options block. The slugify hook can then be written as follows:

// Example hook: Creates a URL-friendly version (slug) of a field
function slugify(text) {
  return text.toString().toLowerCase()
    .replace(/\s+/g, '-')
    .replace(/[^\w\-]+/g, '')
    .replace(/\-\-+/g, '-')
    .replace(/^-+/, '')
    .replace(/-+$/, '')
}

module.exports = function (obj, type, data) {
  // We use the options object to know what field to use as the source
  // and what field to populate with the slug
  obj[data.options.to] = slugify(obj[data.options.from])
  return obj
}

Anchor link Before and After Hooks

Different types of hooks are executed at different points in the lifecycle of a request. There are two main types of hooks:

• Before hooks: are always executed, fired just before the model processes the request and grabs the documents from the database. These hooks have the power to modify the query parameters, and therefore modify the set of documents that will be retrieved, as well as to abort an operation completely, if they choose to throw an error;
• After hooks: are executed only if the operation has been successful (i.e. no errors resulting from either before hooks or from the communication with the database). They are fired after the result set has been formed and delivered to the consumer. Before hooks cannot affect the result of a request. Typically used to trigger operations that must take place after a set of documents has been successfully created, updated or deleted.

These hook types are then applied to each of the CRUD operations (e.g. beforeCreate, afterCreate, etc.). If you think of API as an assembly line that processes requests and documents, this is where hooks would sit:

         ______________          __________            _____________ 
Request |              |        |          | Response |             |
------> | beforeCreate | -----> | Database | -------> | afterCreate |
        |______________|        |__________|          |_____________|

Anchor link Types and signatures

Hooks are expected to export a function that receives three parameters:

1. The document or query being processed (type: Object)
2. The name of the hook type (type: String, example: "beforeCreate")
3. An object with additional data that varies with each hook type (type: Object)

Anchor link beforeCreate

Fires for POST requests, before documents are inserted into the database.

Parameters:

1. documents: An object or array of objects representing the documents about to be created
2. type: A string containing "beforeCreate"
3. options: An options object containing:
   • collection: name of the current collection
   • options: options block from the hook definition in the collection schema
   • req: the instance of Node's http.IncomingMessage
   • schema: the schema of the current collection

Returns:

The new set of documents to be inserted. An error can be thrown to abort the operation.

Anchor link afterCreate

Fires for POST requests, if and after the documents have been successfully inserted.

Parameters:

1. documents: An object or array of objects representing the documents created
2. type: A string containing "afterCreate"
3. options: An options object containing:
   • collection: name of the current collection
   • options: options block from the hook definition in the collection schema
   • schema: the schema of the current collection

Returns:

N/A

Anchor link beforeDelete

Fires for DELETE requests, before data is deleted from the database.

Parameters:

1. query: A query that will be used to filter documents for deletion
2. type: A string containing "beforeDelete"
3. options: An options object containing:
   • collection: name of the current collection
   • options: options block from the hook definition in the collection schema
   • req: the instance of Node's http.IncomingMessage
   • schema: the schema of the current collection
   • deletedDocs: an array containing the documents that are about to be deleted

Returns:

The new query to filter documents with. An error can be thrown to abort the operation.

Anchor link afterDelete

Fires for DELETE requests, if and after the documents have been successfully deleted.

Parameters:

1. query: A query that was used to filter documents for deletion
2. type: A string containing "afterDelete"
3. options: An options object containing:
   • collection: name of the current collection
   • options: options block from the hook definition in the collection schema
   • schema: the schema of the current collection
   • deletedDocs: an array containing the documents that are about to be deleted

Returns:

N/A

Anchor link beforeGet

Fires for GET requests, before documents are retrieved from the database.

Parameters:

1. query: A query that will be used to filter documents
2. type: A string containing "beforeGet"
3. options: An options object containing:
   • collection: name of the current collection
   • options: options block from the hook definition in the collection schema
   • req: the instance of Node's http.IncomingMessage
   • schema: the schema of the current collection

Returns:

The new query to filter documents with. An error can be thrown to abort the operation.

Anchor link afterGet

Fires for GET requests. Unlike other after hooks, afterGet happens after the data has been retrieved but before the response is sent to the consumer. As a consequence, afterGet hooks have the ability to massage the data before it's delivered.

Parameters:

1. documents: An object or array of objects representing the documents retrieved
2. type: A string containing "afterGet"
3. options: An options object containing:
   • collection: name of the current collection
   • options: options block from the hook definition in the collection schema
   • req: the instance of Node's http.IncomingMessage
   • schema: the schema of the current collection

Returns:

The result set formatted for output. An error can be thrown to abort the operation.

Anchor link beforeUpdate

Fires for PUT requests, before documents are updated on the database.

Parameters:

1. update: An object with the set of fields to be updated and their respective new values
2. type: A string containing "beforeUpdate"
3. options: An options object containing:
   • collection: name of the current collection
   • options: options block from the hook definition in the collection schema
   • req: the instance of Node's http.IncomingMessage
   • schema: the schema of the current collection
   • updatedDocs: the documents about to be updated

Returns:

The new update object. An error can be thrown to abort the operation.

Anchor link afterUpdate

Fires for PUT requests, if and after the documents have been successfully updated.

Parameters:

1. documents: An object or array of objects representing the documents updated
2. type: A string containing "afterUpdate"
3. options: An options object containing:
   • collection: name of the current collection
   • options: options block from the hook definition in the collection schema
   • schema: the schema of the current collection

Returns:

N/A

Anchor link Testing

The following hook may be useful to get a better idea of when exactly each hook type is fired and what data it receives, as it logs to the console its internals every time it gets called:

workspace/hooks/showInfo.js

module.exports = function (obj, type, data) {
  console.log('')
  console.log('Hook type:', type)
  console.log('Payload:', obj)
  console.log('Additional data:', data)
  console.log('')

  return obj
}

And then enable it in a model:

workspace/collections/vjoin/testdb/collection.users.json

"hooks": {
  "beforeCreate": ["showInfo"],
  "afterCreate": ["showInfo"],
  "beforeUpdate": ["showInfo"],
  "afterUpdate": ["showInfo"],
  "beforeDelete": ["showInfo"],
  "afterDelete": ["showInfo"]
}

Anchor link Internal Endpoints

Anchor link Hello

The Hello endpoint returns a plain text response with the string Welcome to API when a GET request is made to the /hello endpoint. It can be used to verify that DADI API is successfully installed and running. You should expect a 200 status code to be returned when requesting this endpoint.

Anchor link Configuration

The /api/config endpoint returns a JSON response with API's current configuration. This endpoint requires authentication by passing a Bearer token in the Authorization header. See the Authentication section for more detail.

GET /api/config HTTP/1.1
Host: api.somedomain.tech
Content-Type: application/json
Cache-Control: no-cache

Anchor link Cache flush

Cached files can be flushed by sending a POST request to API's /api/flush endpoint. The request body must contain a path that matches a collection resource. For example, the following will flush all cache files that match the collection path /1.0/library/books.

POST /api/flush HTTP/1.1
Host: api.somedomain.tech
Authorization: Bearer 4172bbf1-0890-41c7-b0db-477095a288b6
Content-Type: application/json

{ "path": "/1.0/library/books" }

A successful cache flush returns a JSON response with a 200 status code:

{
  "result": "success",
  "message": "Cache flush successful"
}

Anchor link Flush all files

To flush all cache files from the API's caching layer, send * as the path in the request body:

POST /api/flush HTTP/1.1
Host: api.somedomain.tech
Authorization: Bearer 4172bbf1-0890-41c7-b0db-477095a288b6
Content-Type: application/json

{ "path": "*" }

Anchor link All Collections

The /api/collections endpoint returns a JSON response containing information about the available collections that can be queried.

GET /api/collections HTTP/1.1
Host: api.somedomain.tech
Content-Type: application/json
Cache-Control: no-cache

{
  "collections": [
    {
      "name": "books",
      "slug": "books",
      "version": "1.0",
      "database": "library",
      "path": "/1.0/library/books"
    },
    {
      "name": "user",
      "slug": "user",
      "version": "1.0",
      "database": "library",
      "path": "/1.0/library/users"
    },
    {
      "name": "author",
      "slug": "author",
      "version": "1.0",
      "database": "library",
      "path": "/1.0/library/authors"
    }
  ]
}

Anchor link Feature queries

As the feature set of DADI API evolves, it’s possible that two instances running different versions of the product have support for substantially different sets of functionality. Since consumer applications may require a specific feature in order to operate, it becomes essential that applications have a view on the capabilities of the API instance they communicate with. For security reasons, API does not expose its version number, but it does allow clients to inquire about whether a particular feature is supported.

Since version 4.2.0, every new major feature added to the product will be identified by a unique alphanumeric key. Consumer applications can use these keys to query an API instance about whether it supports a particular feature.

To use feature queries, add a X-DADI-Requires header to an API request and include a list of the features to query, separated by semicolons. The response will include a X-DADI-Supports header with the supported subset of the features requested. If none of the features are supported, the header will be omitted from the response.

In practice, this means that consumer applications can adapt to the capabilities of the API instance. For example, let's imagine that your application requires the feature set labeled with the key aclv1. You can send X-DADI-Requires: aclv1 to API and look for a X-DADI-Supports header in the response – if it exists and it contains the value aclv1 somewhere in it, you know the feature is supported. If not, you can make your application gracefully handle the incompatibility problem.

Request

GET /1.0/library/movies HTTP/1.1
Host: api.somedomain.tech
Authorization: Bearer 4172bbf1-0890-41c7-b0db-477095a288b6
Content-Type: application/json
X-DADI-Requires: aclv1

Response

Content-Type: application/json
X-DADI-Supports: aclv1

{
  "results": [
    {
      "_id": "560a5baf320039f1a1b68d4c",
      "title": "Casablanca"
    }
  ]
}

Anchor link Disabling feature queries

API will respond to feature queries by default. This behaviour can be changed by setting the featureQuery.enabled configuration property to false, which makes API ignore the X-DADI-Supports header completely.

Note that consumer applications, such as Publish, make use of API feature queries. Disabling them can cause these applications to stop working properly. Do not change this setting unless you know what you are doing!

Anchor link Feature reference

The following table shows which features can be queried:

Anchor link Data connectors reference

Anchor link MongoDB Connector

The MongoDB connector allows you to use MongoDB as the backend for API. It was extracted from API core as part of the 3.0.0 release. The connector is available as an NPM package, with full source code available on GitHub. Help improve the package at https://github.com/dadi/api-mongodb.

Anchor link Installing

$ npm install --save @dadi/api-mongodb

Anchor link Configuring

As with any of the API data connectors, you need two configuration files. Details regarding the main configuration file can be found elsewhere in this document. Below are the configuration options for your MongoDB configuration file.

These parameters are defined in JSON files placed inside the config/ directory, named as mongodb.{ENVIRONMENT}.json, where {ENVIRONMENT} is the value of the NODE_ENV environment variable. In practice, this allows you to have different configuration parameters for when API is running in development, production and any staging, QA or anything in between.

Some configuration parameters also have corresponding environment variables, which will override whatever value is set in the configuration file.

The following table shows a list of all the available configuration parameters.

{
  "hosts": [
    {
      "host": "127.0.0.1",
      "port": 27017
    }
  ],
  "username": "",
  "password": "",
  "database": "testdb",
  "ssl": false,
  "replicaSet": "",
  "enableCollectionDatabases": true,
  "databases": {
    "testdb": {
      "hosts": [
        {
          "host": "127.0.0.1",
          "port": 27017
        }
      ]
    }
  }
}

Anchor link Using MongoLab

If you're unable to install MongoDB yourself, MongoLab provides a variety of plans to get you running with a MongoDB backend for API. They have a free Sandbox tier that is ideal to get a prototype online. Create an account at https://mlab.com/signup/, verify your email address, and we'll begin configuring API.

Anchor link Create new deployment

Once your account is created with MongoLab you'll need to create a new "MongoDB Deployment". Follow the prompts to create a Sandbox deployment, then click Submit Order on the final screen to provision the service:

Anchor link View MongoDB details

When the database is ready, click on its name to see the details required for connecting to it.

Anchor link Creating a MongoLab database user

MongoLab requires you to create a database user in order to connect:

A database user is required to connect to this database. To create one now, visit the 'Users' tab and click the 'Add database user' button.

Complete the fields in the New User popup and keep a note of the username and password for the next step.

Anchor link Connecting from API

To connect to a MongoDB database you require two configuration files: the first is the main API configuration file (config.development.json) and the second is the configuration file for the MongoDB data connector (mongodb.development.json).

config.development.json

The key settings in the main API configuration file are datastore, auth.datastore and auth.database. When using the MongoDB data connector, datastore must be set to "@dadi/api-mongodb". If using MongoDB for API's authentication data, auth.datastore must also be set to "@dadi/api-mongodb". The auth section also specifies the database to use for authentication data; in the example below it is set to the name of the database we created when setting up the MongoLab database.

{
  "app": {
    "name": "MongoLab Test"
  },
  "server": {
    "host": "127.0.0.1",
    "port": 3000
  },
  "publicUrl": {
    "host": "localhost",
    "port": 3000
  },
  "datastore": "@dadi/api-mongodb",
  "auth": {
    "tokenUrl": "/token",
    "tokenTtl": 18000,
    "clientCollection": "clientStore",
    "tokenCollection": "tokenStore",
    "datastore": "@dadi/api-mongodb",
    "database": "dadiapisandbox"
  },
  "paths": {
    "collections": "workspace/collections",
    "endpoints": "workspace/endpoints",
    "hooks": "workspace/hooks"
  }
}

mongodb.development.json

In addition to the main configuration file, API requires a configuration file specific to the data connector. The configuration file for the MongoDB connector must be located in the config directory along with the main configuration file. mongodb.development.json contains settings for connecting to a MongoDB database.

The database detail page on MongoLab shows a couple of ways to connect to your MongoLab database. We'll take some parameters from the "mongo shell" option and use them in our configuration file:

To connect using the mongo shell: mongo ds159509.mlab.com:59509/dadiapisandbox -u -p

{
  "hosts": [
    {
      "host": "ds159509.mlab.com",
      "port": 59509
    }
  ],
  "username": "dadiapi",  // username for database user created in MongoLab
  "password": "ipaidad",  // password for database user created in MongoLab
  "database": "dadiapisandbox",
  "ssl": false,
  "replicaSet": "",
  "databases": {
    "dadiapisandbox": {
      "authDatabase": "dadiapisandbox",  // the name of the database to use for authenticating, required when specifying a username and password
      "hosts": [
        {
          "host": "ds159509.mlab.com",
          "port": 59509
        }
      ]
    }
  }
}

Anchor link Booting API

When you start your API application it will attempt to connect to the MongoLab database using the specified settings.

$ npm start

After API finishes booting, you can click on the "Collections" tab in the MongoLab website and see the collections that API has created from your workspace collection schemas.