{"id":9,"date":"2026-03-30T15:35:55","date_gmt":"2026-03-30T15:35:55","guid":{"rendered":"http:\/\/dadi.cloud\/api-2\/"},"modified":"2026-03-30T15:35:55","modified_gmt":"2026-03-30T15:35:55","slug":"api-2","status":"publish","type":"page","link":"https:\/\/dadi.cloud\/docs-sub\/api\/","title":{"rendered":"Api"},"content":{"rendered":"
\n

Anchor link<\/a> Requirements<\/a><\/h2>\n

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.<\/p>\n

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<\/a> for further information.<\/p>\n

Anchor link<\/a> Creating an API<\/a><\/h2>\n

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<\/a>.<\/p>\n

Anchor link<\/a> Create new API installation<\/a><\/h3>\n

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<\/code> which it uses to create a directory for the installation.<\/p>\n

Manual directory creation<\/em><\/p>\n

$<\/span> mkdir my-api<\/span>\n$<\/span> cd<\/span> my-api<\/span>\n$<\/span> npx dadi-cli api new<\/span>\n<\/code><\/pre>\n
Automatic directory creation<\/em><\/p>\n
$<\/span> npx dadi-cli api new my-api<\/span>\n$<\/span> cd<\/span> my-api<\/span>\n<\/code><\/pre>\n
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.<\/p>\n
\n
Installing DADI API directly from NPM<\/strong><\/p>\n
All DADI platform microservices are also available from NPM. To add API<\/em> to an existing project as a dependency:<\/p>\n<\/blockquote>\n
\n
$<\/span> cd<\/span> my-existing-node-app<\/span>\n$<\/span> npm install --save @dadi\/api<\/span>\n<\/code><\/pre>\n<\/blockquote>\n
Anchor link<\/a> Application anatomy<\/a><\/h2>\n
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:<\/p>\n
my<\/span>-api\/\n  config\/              # contains environment-specific configuration files<\/span>\n    config.development.json\n  server.js            # the entry point for the application<\/span>\n  package.json\n  workspace\/\n    collections\/       # collection specification files<\/span>\n    endpoints\/         # custom JavaScript endpoints<\/span>\n<\/code><\/pre>\n
Anchor link<\/a> Configuration<\/a><\/h2>\n
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\/<\/code> directory, named as config.{ENVIRONMENT}.json<\/code>, where {ENVIRONMENT}<\/code> is the value of the NODE_ENV<\/code> 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.<\/p>\n
Some configuration parameters also have corresponding environment variables, which will override whatever value is set in the configuration file.<\/p>\n
The following table shows a list of all the available configuration parameters.<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Path<\/th>\nDescription<\/th>\nEnvironment variable<\/th>\nDefault<\/th>\nFormat<\/th>\n<\/tr>\n<\/thead>\n
app.name<\/code><\/td>\nThe applicaton name<\/td>\nN\/A<\/em><\/td>\nDADI API Repo Default<\/code><\/td>\nString<\/td>\n<\/tr>\n
publicUrl.host<\/code><\/td>\nThe host of the URL where the API instance can be publicly accessed at<\/td>\nURL_HOST<\/code><\/td>\n<\/code><\/td>\n*<\/td>\n<\/tr>\n
publicUrl.port<\/code><\/td>\nThe port of the URL where the API instance can be publicly accessed at<\/td>\nURL_PORT<\/code><\/td>\n<\/code><\/td>\n*<\/td>\n<\/tr>\n
publicUrl.protocol<\/code><\/td>\nThe protocol of the URL where the API instance can be publicly accessed at<\/td>\nURL_PROTOCOL<\/code><\/td>\nhttp<\/code><\/td>\nString<\/td>\n<\/tr>\n
server.host<\/code><\/td>\nAccept connections on the specified address. If the host is omitted, the server will accept connections on any IPv6 address (::) when IPv6 is available, or any IPv4 address (0.0.0.0) otherwise.<\/td>\nHOST<\/code><\/td>\n<\/code><\/td>\n*<\/td>\n<\/tr>\n
server.port<\/code><\/td>\nAccept connections on the specified port. A value of zero will assign a random port.<\/td>\nPORT<\/code><\/td>\n8081<\/code><\/td>\nNumber<\/td>\n<\/tr>\n
server.redirectPort<\/code><\/td>\nPort to redirect http connections to https from<\/td>\nREDIRECT_PORT<\/code><\/td>\n<\/code><\/td>\nport<\/td>\n<\/tr>\n
server.protocol<\/code><\/td>\nThe protocol the web application will use<\/td>\nPROTOCOL<\/code><\/td>\nhttp<\/code><\/td>\nString<\/td>\n<\/tr>\n
server.sslPassphrase<\/code><\/td>\nThe passphrase of the SSL private key<\/td>\nSSL_PRIVATE_KEY_PASSPHRASE<\/code><\/td>\n<\/code><\/td>\nString<\/td>\n<\/tr>\n
server.sslPrivateKeyPath<\/code><\/td>\nThe filename of the SSL private key<\/td>\nSSL_PRIVATE_KEY_PATH<\/code><\/td>\n<\/code><\/td>\nString<\/td>\n<\/tr>\n
server.sslCertificatePath<\/code><\/td>\nThe filename of the SSL certificate<\/td>\nSSL_CERTIFICATE_PATH<\/code><\/td>\n<\/code><\/td>\nString<\/td>\n<\/tr>\n
server.sslIntermediateCertificatePath<\/code><\/td>\nThe filename of an SSL intermediate certificate, if any<\/td>\nSSL_INTERMEDIATE_CERTIFICATE_PATH<\/code><\/td>\n<\/code><\/td>\nString<\/td>\n<\/tr>\n
server.sslIntermediateCertificatePaths<\/code><\/td>\nThe filenames of SSL intermediate certificates, overrides sslIntermediateCertificate (singular)<\/td>\nSSL_INTERMEDIATE_CERTIFICATE_PATHS<\/code><\/td>\n<\/code><\/td>\nArray<\/td>\n<\/tr>\n
datastore<\/code><\/td>\nThe name of the NPM module to use as a data connector for collection data<\/td>\nN\/A<\/em><\/td>\n@dadi\/api-mongodb<\/code><\/td>\nString<\/td>\n<\/tr>\n
auth.tokenUrl<\/code><\/td>\nThe endpoint for bearer token generation<\/td>\nN\/A<\/em><\/td>\n\/token<\/code><\/td>\nString<\/td>\n<\/tr>\n
auth.tokenTtl<\/code><\/td>\nNumber of seconds that bearer tokens are valid for<\/td>\nN\/A<\/em><\/td>\n1800<\/code><\/td>\nNumber<\/td>\n<\/tr>\n
auth.clientCollection<\/code><\/td>\nName of the collection where clientId\/secret pairs are stored<\/td>\nN\/A<\/em><\/td>\nclientStore<\/code><\/td>\nString<\/td>\n<\/tr>\n
auth.tokenCollection<\/code><\/td>\nName of the collection where bearer tokens are stored<\/td>\nN\/A<\/em><\/td>\ntokenStore<\/code><\/td>\nString<\/td>\n<\/tr>\n
auth.datastore<\/code><\/td>\nThe name of the NPM module to use as a data connector for authentication data<\/td>\nN\/A<\/em><\/td>\n@dadi\/api-mongodb<\/code><\/td>\nString<\/td>\n<\/tr>\n
auth.database<\/code><\/td>\nThe name of the database to use for authentication<\/td>\nDB_AUTH_NAME<\/code><\/td>\ntest<\/code><\/td>\nString<\/td>\n<\/tr>\n
auth.cleanupInterval<\/code><\/td>\nThe interval (in seconds) at which the token store will delete expired tokens from the database<\/td>\nN\/A<\/em><\/td>\n3600<\/code><\/td>\nNumber<\/td>\n<\/tr>\n
auth.saltRounds<\/code><\/td>\nThe difficulty factor used when hashing client secrets (lower values mean hashes are faster to generate but easier to crack)<\/td>\nN\/A<\/em><\/td>\n10<\/code><\/td>\nNumber<\/td>\n<\/tr>\n
caching.ttl<\/code><\/td>\nNumber of seconds that cached items are valid for<\/td>\nN\/A<\/em><\/td>\n300<\/code><\/td>\nNumber<\/td>\n<\/tr>\n
caching.directory.enabled<\/code><\/td>\nIf enabled, cache files will be saved to the filesystem<\/td>\nN\/A<\/em><\/td>\ntrue<\/code><\/td>\nBoolean<\/td>\n<\/tr>\n
caching.directory.path<\/code><\/td>\nThe relative path to the cache directory<\/td>\nN\/A<\/em><\/td>\n.\/cache\/api<\/code><\/td>\nString<\/td>\n<\/tr>\n
caching.directory.extension<\/code><\/td>\nThe extension to use for cache files<\/td>\nN\/A<\/em><\/td>\njson<\/code><\/td>\nString<\/td>\n<\/tr>\n
caching.directory.autoFlush<\/code><\/td>\nIf true, cached files that are older than the specified TTL setting will be automatically deleted<\/td>\nN\/A<\/em><\/td>\ntrue<\/code><\/td>\nBoolean<\/td>\n<\/tr>\n
caching.directory.autoFlushInterval<\/code><\/td>\nInterval to run the automatic flush mechanism, if enabled in autoFlush<\/code><\/td>\nN\/A<\/em><\/td>\n60<\/code><\/td>\nNumber<\/td>\n<\/tr>\n
caching.redis.enabled<\/code><\/td>\nIf enabled, cache files will be saved to the specified Redis server<\/td>\nREDIS_ENABLED<\/code><\/td>\n<\/code><\/td>\nBoolean<\/td>\n<\/tr>\n
caching.redis.host<\/code><\/td>\nThe Redis server host<\/td>\nREDIS_HOST<\/code><\/td>\n127.0.0.1<\/code><\/td>\nString<\/td>\n<\/tr>\n
caching.redis.port<\/code><\/td>\nThe port for the Redis server<\/td>\nREDIS_PORT<\/code><\/td>\n6379<\/code><\/td>\nport<\/td>\n<\/tr>\n
caching.redis.password<\/code><\/td>\nThe password for the Redis server<\/td>\nREDIS_PASSWORD<\/code><\/td>\n<\/code><\/td>\nString<\/td>\n<\/tr>\n
logging.enabled<\/code><\/td>\nIf true, logging is enabled using the following settings.<\/td>\nN\/A<\/em><\/td>\ntrue<\/code><\/td>\nBoolean<\/td>\n<\/tr>\n
logging.level<\/code><\/td>\nSets the logging level.<\/td>\nN\/A<\/em><\/td>\ninfo<\/code><\/td>\ndebug<\/code> or info<\/code> or warn<\/code> or error<\/code> or trace<\/code><\/td>\n<\/tr>\n
logging.path<\/code><\/td>\nThe absolute or relative path to the directory for log files.<\/td>\nN\/A<\/em><\/td>\n.\/log<\/code><\/td>\nString<\/td>\n<\/tr>\n
logging.filename<\/code><\/td>\nThe name to use for the log file, without extension.<\/td>\nN\/A<\/em><\/td>\napi<\/code><\/td>\nString<\/td>\n<\/tr>\n
logging.extension<\/code><\/td>\nThe extension to use for the log file.<\/td>\nN\/A<\/em><\/td>\nlog<\/code><\/td>\nString<\/td>\n<\/tr>\n
logging.accessLog.enabled<\/code><\/td>\nIf true, HTTP access logging is enabled. The log file name is similar to the setting used for normal logging, with the addition of \\"access\\". For example api.access.log<\/code>.<\/td>\nN\/A<\/em><\/td>\ntrue<\/code><\/td>\nBoolean<\/td>\n<\/tr>\n
logging.accessLog.kinesisStream<\/code><\/td>\nAn AWS Kinesis stream to write to log records to.<\/td>\nKINESIS_STREAM<\/code><\/td>\n<\/code><\/td>\nString<\/td>\n<\/tr>\n
paths.collections<\/code><\/td>\nThe relative or absolute path to collection specification files<\/td>\nN\/A<\/em><\/td>\nworkspace\/collections<\/code><\/td>\nString<\/td>\n<\/tr>\n
paths.endpoints<\/code><\/td>\nThe relative or absolute path to custom endpoint files<\/td>\nN\/A<\/em><\/td>\nworkspace\/endpoints<\/code><\/td>\nString<\/td>\n<\/tr>\n
paths.hooks<\/code><\/td>\nThe relative or absolute path to hook specification files<\/td>\nN\/A<\/em><\/td>\nworkspace\/hooks<\/code><\/td>\nString<\/td>\n<\/tr>\n
feedback<\/code><\/td>\nIf true, responses to DELETE requests will include a count of deleted and remaining documents, as opposed to an empty response body<\/td>\nN\/A<\/em><\/td>\n<\/code><\/td>\nBoolean<\/td>\n<\/tr>\n
status.enabled<\/code><\/td>\nIf true, status endpoint is enabled.<\/td>\nN\/A<\/em><\/td>\n<\/code><\/td>\nBoolean<\/td>\n<\/tr>\n
status.routes<\/code><\/td>\nAn array of routes to test. Each route object must contain properties route<\/code> and expectedResponseTime<\/code>.<\/td>\nN\/A<\/em><\/td>\n<\/code><\/td>\nArray<\/td>\n<\/tr>\n
query.useVersionFilter<\/code><\/td>\nIf true, the API version parameter is extracted from the request URL and passed to the database query<\/td>\nN\/A<\/em><\/td>\n<\/code><\/td>\nBoolean<\/td>\n<\/tr>\n
media.defaultBucket<\/code><\/td>\nThe name of the default media bucket<\/td>\nN\/A<\/em><\/td>\nmediaStore<\/code><\/td>\nString<\/td>\n<\/tr>\n
media.buckets<\/code><\/td>\nThe names of media buckets to be used<\/td>\nN\/A<\/em><\/td>\n<\/code><\/td>\nArray<\/td>\n<\/tr>\n
media.tokenSecret<\/code><\/td>\nThe secret key used to sign and verify tokens when uploading media<\/td>\nN\/A<\/em><\/td>\ncatboat-beatific-drizzle<\/code><\/td>\nString<\/td>\n<\/tr>\n
media.tokenExpiresIn<\/code><\/td>\nThe duration a signed token is valid for. Expressed in seconds or a string describing a time span (https:\/\/github.com\/zeit\/ms). Eg: 60, \\"2 days\\", \\"10h\\", \\"7d\\"<\/td>\nN\/A<\/em><\/td>\n1h<\/code><\/td>\n*<\/td>\n<\/tr>\n
media.storage<\/code><\/td>\nDetermines the storage type for uploads<\/td>\nN\/A<\/em><\/td>\ndisk<\/code><\/td>\ndisk<\/code> or s3<\/code><\/td>\n<\/tr>\n
media.basePath<\/code><\/td>\nSets the root directory for uploads<\/td>\nN\/A<\/em><\/td>\nworkspace\/media<\/code><\/td>\nString<\/td>\n<\/tr>\n
media.pathFormat<\/code><\/td>\nDetermines the format for the generation of subdirectories to store uploads<\/td>\nN\/A<\/em><\/td>\ndate<\/code><\/td>\nnone<\/code> or date<\/code> or datetime<\/code> or sha1\/4<\/code> or sha1\/5<\/code> or sha1\/8<\/code><\/td>\n<\/tr>\n
media.s3.accessKey<\/code><\/td>\nThe S3 access key used to connect to S3<\/td>\nAWS_S3_ACCESS_KEY<\/code><\/td>\n<\/code><\/td>\nString<\/td>\n<\/tr>\n
media.s3.secretKey<\/code><\/td>\nThe S3 secret key used to connect to S3<\/td>\nAWS_S3_SECRET_KEY<\/code><\/td>\n<\/code><\/td>\nString<\/td>\n<\/tr>\n
media.s3.bucketName<\/code><\/td>\nThe name of the AWS S3 or Digital Ocean Spaces bucket in which to store uploads<\/td>\nAWS_S3_BUCKET_NAME<\/code><\/td>\n<\/code><\/td>\nString<\/td>\n<\/tr>\n
media.s3.region<\/code><\/td>\nThe S3 region<\/td>\nAWS_S3_REGION<\/code><\/td>\n<\/code><\/td>\nString<\/td>\n<\/tr>\n
media.s3.endpoint<\/code><\/td>\nThe S3 endpoint, required for accessing a Digital Ocean Space<\/td>\n<\/td>\n<\/td>\nString<\/td>\n<\/tr>\n
env<\/code><\/td>\nThe applicaton environment.<\/td>\nNODE_ENV<\/code><\/td>\ndevelopment<\/code><\/td>\nString<\/td>\n<\/tr>\n
cluster<\/code><\/td>\nIf true, API runs in cluster mode, starting a worker for each CPU core<\/td>\nN\/A<\/em><\/td>\n<\/code><\/td>\nBoolean<\/td>\n<\/tr>\n
cors<\/code><\/td>\nIf true, responses will include headers for cross-domain resource sharing<\/td>\nN\/A<\/em><\/td>\n<\/code><\/td>\nBoolean<\/td>\n<\/tr>\n
internalFieldsPrefix<\/code><\/td>\nThe character to be used for prefixing internal fields<\/td>\nN\/A<\/em><\/td>\n_<\/code><\/td>\nString<\/td>\n<\/tr>\n
databaseConnection.maxRetries<\/code><\/td>\nThe maximum number of times to reconnection attempts after a database fails<\/td>\nN\/A<\/em><\/td>\n10<\/code><\/td>\nNumber<\/td>\n<\/tr>\n
i18n.defaultLanguage<\/code><\/td>\nISO-639-1 code of the default language<\/td>\nN\/A<\/em><\/td>\nen<\/code><\/td>\nString<\/td>\n<\/tr>\n
i18n.languages<\/code><\/td>\nList of ISO-639-1 codes for the supported languages<\/td>\nN\/A<\/em><\/td>\n[]<\/code><\/td>\nArray<\/td>\n<\/tr>\n
i18n.fieldCharacter<\/code><\/td>\nSpecial character to denote a translated field<\/td>\nN\/A<\/em><\/td>\n:<\/code><\/td>\nString<\/td>\n<\/tr>\n
search.enabled<\/code><\/td>\nIf true, API responds to collection \/search endpoints and will index content<\/td>\nN\/A<\/em><\/td>\nfalse<\/code><\/td>\nBoolean<\/td>\n<\/tr>\n
search.minQueryLength<\/code><\/td>\nMinimum search string length<\/td>\nN\/A<\/em><\/td>\n3<\/code><\/td>\nNumber<\/td>\n<\/tr>\n
search.wordCollection<\/code><\/td>\nThe name of the datastore collection that will hold tokenized words<\/td>\nN\/A<\/em><\/td>\nwords<\/code><\/td>\nString<\/td>\n<\/tr>\n
search.datastore<\/code><\/td>\nThe datastore module to use for storing and querying indexed documents<\/td>\nN\/A<\/em><\/td>\n@dadi\/api-mongodb<\/code><\/td>\nString<\/td>\n<\/tr>\n
search.database<\/code><\/td>\nThe name of the database to use for storing and querying indexed documents<\/td>\nDB_SEARCH_NAME<\/code><\/td>\nsearch<\/code><\/td>\nString<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Anchor link<\/a> Authentication<\/a><\/h2>\n
DADI API provides a full-featured authentication layer based on the Client Credentials flow of oAuth 2.0<\/a>. Consumers must exchange a set of client credentials for a temporary access token, which must be appended to API requests.<\/p>\n
A client is represented as a set of credentials (ID + secret) and an access type, which can be set to admin<\/code> or user<\/code>. If set to admin<\/code>, 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<\/a>.<\/p>\n
Anchor link<\/a> Adding clients<\/a><\/h3>\n
If you've installed DADI CLI<\/a> you can use that to create a new client in the database. See instructions for Adding clients with CLI<\/a>.<\/p>\n
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.<\/p>\n
$ npm<\/span> explore @dadi\/api -- npm<\/span> run create-client\n<\/code><\/pre>\n
\n
Creating the client in the correct database<\/strong><\/p>\n
To ensure the correct database is used for your environment, add an environment variable to the command:<\/p>\n
$ NODE_ENV<\/span>=production npm explore @dadi\/api -- npm run<\/span> create-client\n<\/code><\/pre>\n<\/blockquote>\n
Anchor link<\/a> Obtaining an access token<\/a><\/h3>\n
Obtain an access token by sending a POST<\/code> 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<\/code><\/a>, with a default value of \/token<\/code>.<\/p>\n
POST<\/span> \/token<\/span> HTTP\/1.1\nContent-Type<\/span>: application\/json\nHost<\/span>: api.somedomain.tech\nConnection<\/span>: close\nContent-Length<\/span>: 65\n{\n  \"clientId\"<\/span>: \"my-client-key\"<\/span>,\n  \"secret\"<\/span>: \"my-client-secret\"<\/span>\n}<\/span>\n<\/code><\/pre>\n
With a request like the above, you should expect a response containing an access token, as below:<\/p>\n
HTTP\/1.1 200<\/span> OK\nContent-Type<\/span>: application\/json\nCache-Control<\/span>: no-store\nContent-Length<\/span>: 95\n{\n  \"accessToken\"<\/span>: \"4172bbf1-0890-41c7-b0db-477095a288b6\"<\/span>,\n  \"tokenType\"<\/span>: \"Bearer\"<\/span>,\n  \"expiresIn\"<\/span>: 3600<\/span>,\n  \"accessType\"<\/span>: \"admin\"<\/span>\n}<\/span>\n<\/code><\/pre>\n
Anchor link<\/a> Using an access token<\/a><\/h3>\n
Once you have an access token, each request to the API should include an Authorization<\/code> header containing the token:<\/p>\n
GET<\/span> \/1.0\/library\/books<\/span> HTTP\/1.1\nContent-Type<\/span>: application\/json\nAuthorization<\/span>: Bearer 4172bbf1-0890-41c7-b0db-477095a288b6\nHost<\/span>: api.somedomain.tech\nConnection<\/span>: close\n<\/code><\/pre>\n
Anchor link<\/a> Internal collections<\/a><\/h3>\n
Internally, API uses three collections to store authentication data:<\/p>\n
Anchor link<\/a> Access token expiry<\/a><\/h3>\n
The response returned when requesting an access token contains a property expiresIn<\/code> 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<\/a>.<\/p>\n
The consumer application must request a new access token to continue communicating with the API.<\/p>\n