Version 2.3.1

Changed

Small fix to ensure stdout streams aren't merged with the options being passed to the logger instance.

Version 2.3.0

This release adds the ability to pass options to the instance of @dadi/logger, and works hand-in-hand with dadi/logger#53.

Version 2.2.11

Changed

#380: remove blocking on cache clear during POST & PUT operations

Version 2.2.10

Changed

#363: creates a global cross-origin middleware that applies spec-compliant CORS headers to all incoming requests.

Version 3.0.0

Added

Data Connectors

API Version 3.0 supports multiple data connectors. In previous versions API used MongoDB as a backend; this is now configurable. API Data Connectors are available as NPM packages. To add one to your API installation, run the associated NPM install command:

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

This step isn't required for using the MongoDB connector, as it is bundled with API by default

Each data connector has it's own configuration requirements, but API must also be configured to use the data connectors you select. Modify your API configuration as follows:

{
  "datastore": "@dadi/api-mongodb",  // the NPM package name for the data connector to use for the content layer
  "auth": {
    "tokenUrl": "/token",
    "tokenTtl": 1800,
    "clientCollection": "clientStore",
    "tokenCollection": "tokenStore",
    "datastore": "@dadi/api-mongodb",  // the NPM package name for the data connector to use for the authentication layer
    "database": "test"
  }
}

In addition, the data connector itself normally requires it's own configuration file. For example the MongoDB data connector requires a file using the following naming convention mongodb.<environment>.json. These configuration files should be placed the config directory of the API application.

Connection Recovery

API is now capable of recovering from database connection failures. When API is started with no available database service it will keep retrying until a successful connection can be made, then it runs the normal boot process.

In addition, if the database connection is lost during normal operation of API, any requests made while the connection is offline will result in a HTTP 503 returned to the client.

The maximum number of connection retries can be configured in the main configuration file by adding the following block:

"databaseConnection": {
  "maxRetries": 5   // default 10
}

Additional connection recovery options are thus far non-configurable, but use these defaults:

• maximum reconnection delay. Defaults to Infinity.
• minimum reconnection delay. Defaults to 500 ms.
• reconnect timeout - time you have to reconnect to the server. If it takes longer, we schedule another reconnection attempt. Defaults to 30 seconds.
• exponential back off factor. Defaults to 2.

/hello

We've added a new /hello endpoint which returns HTTP 200 and a "Welcome to API" message. Closes #251.

Null values

In API Version 3.0 and above, document properties with null values are not returned as part of the response. Closes #180.

Internal fields

We've made a change to the way internal fields are stored in documents. In earlier versions of API we stored the following internal fields within a document:

• history
• composed
• createdAt
• createdBy
• lastModifiedAt
• lastModifiedBy
• apiVersion
• v

In addition, history revision documents are given two extra properties:

• originalDocumentId
• action

In Version 3.0 and above the internal fields will be prefixed with a special character (_ by default) which is configurable using the configuration property internalFieldsPrefix. A document in API will now have internal fields denoted as follows:

{
  _history: [],
  _composed: {},
  _createdAt: "",
  _createdBy: "",
  _lastModifiedAt: "",
  _lastModifiedBy: "",
  _apiVersion: "",
  _version: ""
}

Note: the version identifier v has been renamed _version.

Closes #141.

Delete hooks

All delete hooks now receive a deletedDocs property. Closes #263.

Deleting documents

When configuration option feedback is true we now send a response body when deleting documents.

{
  status: 'success',
  message: 'Documents deleted successfully',
  deletedCount: 1, // number of documents deleted
  totalCount: 100 // remaining documents in the collection
}

Closes #314.

Changed

• #141: the internal fields will be prefixed with a special character (_ by default) which is configurable using the configuration property internalFieldsPrefix
• #180: document properties with null values are not returned as part of the response
• #251: added a new /hello endpoint which returns HTTP 200 and a "Welcome to API" message
• #263: all delete hooks now receive a deletedDocs property
• #314: when configuration option feedback is true we now send a response body when deleting documents
• #327: API becomes capable of recovering from database connection failures
• #328: remove schema validation on settings: 'callback', 'defaultFilters', 'fieldLimiters' and 'count'. Now only requires 'cache' and 'authenticate'
• #332: allow POST to collection endpoints using text/plain content-type, which will be converted if it is valid JSON
• Configuration file validation removed, suppressing warnings on application startup
• POST/PUT/DELETE using non-existing document identifiers returns a 404:

DELETE requests throws a 404 (instead of 204) when deleting a non-existing document by ID. This applies to requests where the document ID is passed in the URL, not when in the body (e.g. DELETE /v1/db/collection/DOC-ID vs DELETE /v1/db/collection).

POST/PUT requests throw a 404 when updating a non-existing document by ID. This applies to requests where the document ID is passed in the URL, not when in the body (e.g. PUT /v1/db/collection/DOC-ID vs PUT /v1/db/collection).

Closes #345.

Version 2.2.9

Changed

Fix previous release 2.2.8: #363: allow OPTIONS method when calling the token route

Version 3.0 Beta

Added

Data Connectors

API Version 3.0 supports multiple data connectors. In previous versions API used MongoDB as a backend; this is now configurable. API Data Connectors are available as NPM packages. To add one to your API installation, run the associated NPM install command:

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

This step isn't required for using the MongoDB connector, as it is bundled with API by default

Each data connector has it's own configuration requirements, but API must also be configured to use the data connectors you select. Modify your API configuration as follows:

{
  "datastore": "@dadi/api-mongodb",  // the NPM package name for the data connector to use for the content layer
  "auth": {
    "tokenUrl": "/token",
    "tokenTtl": 1800,
    "clientCollection": "clientStore",
    "tokenCollection": "tokenStore",
    "datastore": "@dadi/api-mongodb",  // the NPM package name for the data connector to use for the authentication layer
    "database": "test"
  }
}

In addition, the data connector itself normally requires it's own configuration file. For example the MongoDB data connector requires a file using the following naming convention mongodb.<environment>.json. These configuration files should be placed the config directory of the API application.

Connection Recovery

API is now capable of recovering from database connection failures. When API is started with no available database service it will keep retrying until a successful connection can be made, then it runs the normal boot process.

In addition, if the database connection is lost during normal operation of API, any requests made while the connection is offline will result in a HTTP 503 returned to the client.

The maximum number of connection retries can be configured in the main configuration file by adding the following block:

"databaseConnection": {
  "maxRetries": 5   // default 10
}

Additional connection recovery options are thus far non-configurable, but use these defaults:

• maximum reconnection delay. Defaults to Infinity.
• minimum reconnection delay. Defaults to 500 ms.
• reconnect timeout - time you have to reconnect to the server. If it takes longer, we schedule another reconnection attempt. Defaults to 30 seconds.
• exponential back off factor. Defaults to 2.

/hello

We've added a new /hello endpoint which returns HTTP 200 and a "Welcome to API" message. Closes #251.

Null values

In API Version 3.0 and above, document properties with null values are not returned as part of the response. Closes #180.

Internal fields

We've made a change to the way internal fields are stored in documents. In earlier versions of API we stored the following internal fields within a document:

• history
• composed
• createdAt
• createdBy
• lastModifiedAt
• lastModifiedBy
• apiVersion
• v

In addition, history revision documents are given two extra properties:

• originalDocumentId
• action

In Version 3.0 and above the internal fields will be prefixed with a special character (_ by default) which is configurable using the configuration property internalFieldsPrefix. A document in API will now have internal fields denoted as follows:

{
  _history: [],
  _composed: {},
  _createdAt: "",
  _createdBy: "",
  _lastModifiedAt: "",
  _lastModifiedBy: "",
  _apiVersion: "",
  _version: ""
}

Note: the version identifier v has been renamed _version.

Closes #141.

Delete hooks

All delete hooks now receive a deletedDocs property. Closes #263.

Deleting documents

When configuration option feedback is true we now send a response body when deleting documents.

{
  status: 'success',
  message: 'Documents deleted successfully',
  deletedCount: 1, // number of documents deleted
  totalCount: 100 // remaining documents in the collection
}

Closes #314.

Changed

• #141: the internal fields will be prefixed with a special character (_ by default) which is configurable using the configuration property internalFieldsPrefix
• #180: document properties with null values are not returned as part of the response
• #251: added a new /hello endpoint which returns HTTP 200 and a "Welcome to API" message
• #263: all delete hooks now receive a deletedDocs property
• #314: when configuration option feedback is true we now send a response body when deleting documents
• #327: API becomes capable of recovering from database connection failures
• #328: remove schema validation on settings: 'callback', 'defaultFilters', 'fieldLimiters' and 'count'. Now only requires 'cache' and 'authenticate'
• #332: allow POST to collection endpoints using text/plain content-type, which will be converted if it is valid JSON
• Configuration file validation removed, suppressing warnings on application startup
• POST/PUT/DELETE using non-existing document identifiers returns a 404:

DELETE requests throws a 404 (instead of 204) when deleting a non-existing document by ID. This applies to requests where the document ID is passed in the URL, not when in the body (e.g. DELETE /v1/db/collection/DOC-ID vs DELETE /v1/db/collection).

POST/PUT requests throw a 404 when updating a non-existing document by ID. This applies to requests where the document ID is passed in the URL, not when in the body (e.g. PUT /v1/db/collection/DOC-ID vs PUT /v1/db/collection).

Closes #345.

Version 3.0.0 (RC 1)

New features

Data connectors

API Version 3.0 supports multiple data connectors. In previous versions API used MongoDB as a backend; this is now configurable.

Data connector installation

API Data Connectors are available as NPM packages. To add one to your API installation, run the associated NPM install command:

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

Data connector configuration

Each data connector has it's own configuration requirements, but API must also be configured to use the data connectors you select. Modify your API configuration as follows:

{
  "datastore": "@dadi/api-mongodb",  // the NPM package name for the data connector to use for the content layer
  "auth": {
    "tokenUrl": "/token",
    "tokenTtl": 1800,
    "clientCollection": "clientStore",
    "tokenCollection": "tokenStore",
    "datastore": "@dadi/api-mongodb",  // the NPM package name for the data connector to use for the authentication layer
    "database": "test"
  }
}

API requires that each data connector has a configuration file in the same config/ directory as the API configuration files. For example, if using @dadi/api-mongodb you need a configuration file named mongodb.development.json (one for each of the environments you run API in).

Currently available data connectors

• MongoDB

Data connectors in development

• JSON file
• CouchDB

Write a data connector

We'd love for you to write a data connector of your own! We'll shortly release a template on GitHub to get you started.

Changed

/hello

We've added a new /hello endpoint which returns HTTP 200 and a "Welcome to API" message. Closes #251.

Null values

In API Version 3.0 and above, document properties with null values are not returned as part of the response. Closes #180.

Internal fields

We've made a change to the way internal fields are stored in documents. In earlier versions of API we stored the following internal fields within a document:

• history
• composed
• createdAt
• createdBy
• lastModifiedAt
• lastModifiedBy
• apiVersion
• v

In addition, history revision documents are given two extra properties:

• originalDocumentId
• action

In Version 3.0 and above the internal fields will be prefixed with a special character (_ by default) which is configurable using the configuration property internalFieldsPrefix. A document in API will now have internal fields denoted as follows:

{
  _history: [],
  _composed: {},
  _createdAt: "",
  _createdBy: "",
  _lastModifiedAt: "",
  _lastModifiedBy: "",
  _apiVersion: "",
  _version: ""
}

Note: the version identifier v has been renamed _version.

Closes #141.

Delete hooks

All delete hooks now receive a deletedDocs property. Closes #263.

Deleting documents

When configuration option feedback is true we now send a response body when deleting documents.

{
  status: 'success',
  message: 'Documents deleted successfully',
  deletedCount: 1, // number of documents deleted
  totalCount: 100 // remaining documents in the collection
}

Closes #314.

Version 2.2.0

Changed

#289: improved error response from hooks, with custom error support
#311: fix a bug that caused multiple newly-created reference field subdocuments to be returned as a poorly-formed array

Version 2.1.2

Changed

#289: improved error response from hooks
#305: remove restriction on environment settings. Use any environment name and configuration file, rather than only "development", "qa", "production", "test"
#306: fix reference field composition when value is an empty array