Skip to content

Version 3.0.0
Compare
Choose a tag to compare
@jimlambie jimlambie released this 07 Dec 14:05
· 803 commits to develop since this release
v3.0.0
cdaa228

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.

Assets 2
Loading