Versioning & Upgrades

Understanding NLP API Component Versions

The Components

NLP API clinical NLP system consists of the main processing engine, NLP API Engine, and the interfaces and tools used to access the data processing and extraction capabilities of the engine.

The NLP API engine is updated approximately every 2-4 weeks. As we do not release every version we make, the release numbering may not be monotonic. Each release may consist of changes to only some of the components of the system.

The components of the NLP API are:

  • NLP API Engine - the main NLP processing engine, ontology databases, and request management infrastructure.
  • NLP API - the NLP API is a REST interface for submitting reports to NLP API Engine. Its versioning conventions is described in more detail in the versioning.html document. As new features are added to the NLP API, for example when we add new relations or ontologies, these features are deployed to the API endpoint, and the API version number is incremented.
  • NLP API Client Applications & SDKs - Client SDKs provide a language-specific programmatic interface for customers who wish to develop their own client. Python, Java and C# languages are currently supported. The Client SDKs come with ready-to-use Client applications which also serve as code samples. The version number is incremented when a new SDK is released, which can happen in several cases:
    • when the API changes - when it is possible to request a new feature or interact with the API via a new method
    • when the result format changes - so that the client(s) can deal with the output changes appropriately
    • when new client features or modules/libraries are available - we release new client features from time to time to better meet customer needs or fix bugs, or when we update the modules/libraries included with the SDKs
  • Result Format - this is the format of the NLP API’s output. It necessarily changes as new features are added to the engine, and it may also change as tweaks and improvements are made for clarity or to fix bugs. The Result Format major version number is indicated in the output document by the format: field. Result Format versions 2.x are indicated as "format": "emtellipro-json-2", and likewise result format versions 3.x would be indicated as "format": "emtellipro-json-3" in the output.

Versioning of Releases & Components

NLP API releases are versioned with the same number as the NLP API Engine, and they are numbered as follows:

  • The digits preceding the separator (’.’) indicates the Result Format compatiblity. For example NLP API release 2.15 is compatible with Result Format version 2.x. Note, therefore, the output of Result Format 1.x would be incompatible with NLP API version 2.15.
  • The digits following the separator is the release number. Hence, NLP API release 2.15 refers to the 15th release.

Unlike the NLP API Engine, all other components (SDKs, Clients and Result Format) indicate breaking vs. non-breaking changes by versioning in the spirit of semantic versioning.

You can find information about each release here Release Notes.

Compatibility

New releases of the NLP API may introduce breaking changes in one or more of its components. In general any changes to NLP API Engine itself is backward compatible for all existing customer integrations for a given MAJOR Result Format. For example, all 2.x releases of the NLP API is compatible with all data integrations implemented for Result Format v2.x (i.e. output document format ‘emtellipro-json-2’) as long as the customer’s integration does not do strict validation of output JSON or otherwise make assumptions about JSON fields it does not access. This allows us to extend the result format without impacting existing customers.

However, a release may contain breaking changes to other interfaces or components used by the customer, such as the client SDK itself, the command-line client application or its database schema (where applicable). To assess if a breaking change affects you and determine if you need to upgrade a component please refer to Client and Database Upgrade Considerations.