A high-performance RESTful API layer designed in support of API-first development and COPE. Connects your content to the world
Switch branches/tags
1.16.6 2.2.x 2.3.x 3.x develop feat/dd feat/standard-search feature/acl-improvements feature/acl feature/arbitrary-data feature/collections-endpoint-schemas feature/datetime-test feature/default-cors feature/extract-reference-field feature/feature-query feature/hook-return-check feature/http2-node10 feature/http2 feature/index-on-update-delete feature/jenkins feature/language-field-character feature/media-bulk feature/media-field feature/media-metadata feature/media-updates-from-2.x feature/media-validation feature/multi-lang feature/non-blocking-cache-clear feature/remove-config-endpoints feature/return-after-get-hook-error feature/strip-internal-properties feature/support-gzip feature/update-secret feature/validation-module fix/bump-logger-version fix/compose-return-new-copy fix/duplicate-client-check fix/remove-duplicate-logging-setup master patch/acl-fixes-2 patch/acl-fixes patch/acl-serialisation patch/collection-slug patch/extend-json-content-type patch/lang-fields patch/media-field-legacy patch/media-field-null patch/media-url-property patch/nested-object-query patch/non-blocking-clearcache patch/roles-permissions patch/snapshot-stringify-objects patch/tests-for-filter-params patch/1.16.8 patch/2.2.5 release-3.0.0 release-3.2.0 release-3.2.1 release-3.2.2 release-4.0.0 release-4.0.1 release-4.0.2 release-4.0.3 release-4.0.4 release-4.1.0 release-4.1.1 release-4.2.0 release-4.2.1 release-4.2.2 release-4.3.0 release-4.4.0 release-4.4.1 release-4.4.2 release-4.4.3 test/2.2.x-branch tests/acl
Nothing to show
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Create ISSUE_TEMPLATE Feb 25, 2016
config Merge branch 'develop' of https://github.com/dadi/api into feature/se… Jul 22, 2018
dadi/lib fix: add url property to Media field output Nov 29, 2018
scripts chore: add branch name check to precommit Sep 19, 2018
test fix: add url property to Media field output Nov 29, 2018
utils fix duplicate id check Aug 21, 2018
workspace Merge branch 'develop' of https://github.com/dadi/api into feature/se… Jul 9, 2018
.gitignore chore: make test workspace directory ephemeral Jun 6, 2018
.npmignore chore: update dependencies, add .npmignore Jun 6, 2018
.snyk fix: .snyk & package.json to reduce vulnerabilities Oct 19, 2018
.travis.yml chore: use specific Node versions for CI Mar 3, 2018
AUTHORS chore: add contributors May 12, 2017
CHANGELOG.md chore: version 4.4.3 Nov 29, 2018
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md Jun 26, 2017
CONTRIBUTING.md chore: update contributing guidelines Apr 21, 2017
GPL.md chore: update and rename license file Feb 24, 2017
LICENCE Licence updates Jan 17, 2016
README.md chore: increase coverage 🎉 🎉 🎉 Jun 14, 2018
config.js feat: add feature query headers Aug 16, 2018
error-codes.json refactor: use API error codes for invalid/missing current secret Aug 15, 2018
features.json feat: add mediafieldv1 feature code Nov 22, 2018
index.js fix: move start sequence Jun 25, 2016
main.js feat: add ACL export Aug 1, 2018
package.json chore: version 4.4.3 Nov 29, 2018
start.js chore: apply linting fixes Jun 1, 2018



npm (scoped) coverage Build Status JavaScript Style Guide



DADI API is built on Node.JS. It is a high performance RESTful API layer designed in support of API-first development and the principle of COPE. It can use virtually any database engine, such as MongoDB, CouchDB, RethinkDB or simply a JSON filestore.

You can consider it as the data layer within a platform (including the data model). It is designed to be plugged into a templating layer (such as DADI Web), a mobile application or to be used with any other data consumer.

Calls to a DADI API can contain your business/domain logic (the part of a platform that encodes the real-world business rules that determine how data is created, displayed, stored and changed). It has full support for searching, filtering, limiting, sorting, offsetting, input validation and data aggregation (through support for MongoDB's aggregation pipeline).

It has built-in support for oAuth2, includes full collection-level ACL, can connect to multiple databases out of the box, provides native document versioning at collection level, supports static endpoints, includes automatic indexing, has a caching layer and can be run in a clustered configuration.

DADI API provides a starting point that's further advanced than a framework. It allows you to get a complete data layer up and running in minutes.

It is part of DADI, a suite of components covering the full development stack, built for performance and scale.


Your first API project

Install API

The quickest way to get started with API is to use DADI CLI. See Creating an API for full installation details.


API starts with some sensible defaults, so it's not necessary to understand all the configuration options available when first running the application.

Configuration is handled using JSON files specific to the application environment. For example in the production environment a file named config.production.json will be used. Configuration files must be placed in a config folder in your application root, for example config/config.production.json. The default start up environment is development, using the configuration file at config/config.development.json.

The bare minimum required for running the API is a server block. With only a server block, default values are used for all other properties.

Sample configuration

  "server": {
    "host": "",
    "port": 3000

Start the server

API can be started from the command line simply by issuing the following command:

$ npm start

Test the connection

With the default configuration, our API server is available at http://localhost:3000. If you've modified the configuration file's server block, your API will be available at the address and port you've chosen. Use cURL to check the server is running, if the connection can be made you will receive the following "Unauthorised" message.

$ curl http://localhost:3000
{ "statusCode": 401 }

Check the response headers

$ curl -I http://localhost:3000
HTTP/1.1 401 Unauthorized
content-type: application/json
content-length: 18
Date: Thu, 20 Apr 2017 23:42:25 GMT
Connection: keep-alive


The HTTP 401 response received in the previous step shows that the server is running. To start using the REST endpoints you'll need a user account so you can obtain access tokens for interacting with the API.

User accounts provide an authentication layer for API. Each user account has a clientId and a secret. These are used to obtain access tokens for interacting with the API. See the Authentication section of the API documentation for full details.

Creating the first user

CLI contains an interactive "Client Record Generator" to help you create user accounts. Run the following command in the directory where you installed API:

cd my-new-api
dadi api clients:add

If you need to create user accounts in other environments (for example following a deployment to a live server), add the environment to the following command:

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

Run API as a service

To run your API application in the background as a service, install Forever and Forever Service:

$ npm install forever forever-service -g

$ sudo forever-service install -s index.js -e "NODE_ENV=production" api --start

You can now interact with the api service using the following commands:

$ [sudo] service api start
$ [sudo] service api stop
$ [sudo] service api status
$ [sudo] service api restart

Note: the environment variable NODE_ENV=production must be set to the required configuration version matching the configuration files available in the config directory.


To run the tests after cloning the repository, run the following command:

$ npm test

NOTE: API installs version 4.0.1 of Mocha and uses this when calling npm test. If you have Mocha installed globally and want to simply run mocha, if using version 4 or above, add --exit to the command so it becomes mocha --exit



DADI API is based on an original idea by Joseph Denne. It is developed and maintained by the engineering team at DADI (https://dadi.cloud)


DADI is a data centric development and delivery stack, built specifically in support of the principles of API first and COPE.

Copyright notice
(C) 2018 DADI+ Limited support@dadi.cloud
All rights reserved

This product is part of DADI.
DADI is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version ("the GPL").

If you wish to use DADI outside the scope of the GPL, please contact us at info@dadi.co for details of alternative licence arrangements.

This product may be distributed alongside other components available under different licences (which may not be GPL). See those components themselves, or the documentation accompanying them, to determine what licences are applicable.

DADI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

The GNU General Public License (GPL) is available at http://www.gnu.org/licenses/gpl-3.0.en.html.
A copy can be found in the file GPL.md distributed with these files.

This copyright notice MUST APPEAR in all copies of the product!