/
REST Action Service

REST Action Service

Owned by bcarlsen (Unlicensed)
Oct 31, 2014

Overview

Documents the REST Action Service.

For a self-documenting Swagger API, see http://snomed.terminology.tools/term-server-rest/index.html.

This is a placeholder page with basic information and will be developed to fully document this aspect of the system.

Details

The internal action API performs certain potentially long running operation with progress monitoring, cancel support, and session tracking via explicit session tokens. To perform a potentially long running operation, the application will obtain a session token and then perform a series of calls with that token to check on progress of the task, then obtain results asynchronously. Sessions expire according to a configurable parameter and the resulting data structures they track are discarded.

The REST API for the action service authorizes the user and then calls the corresponding internal action service method. The functionality available here is as follows:

  • Configure action service – takes parameters potentially needed by services and returns a session token.
  • Get progress – takes a session token and reports progress of the current action. The correct use of the service is to perform only one action at a time.
  • Cancel – takes a session token and cancels any long running operation currently in progress under that token.
  • Prepare to classify – takes a terminology and a session token and prepares data structures for full classification. This mostly involves building classifier axioms from the data. In theory, this only needs to be done once per session (assuming only add operations).
  • Classify – takes a session token, verifies that “prepare” successfully completed, and performs a full classification, leaving the classified ontology in memory for later retrieval.
  • Incremental classify – takes a session token, verifies that “prepare” and a full classification were performed, obtains changes since last classification run, adds needed axioms, and performs an incremental classification. Note: incremental classification is not supported if changes include retirement or removal of content – only additions are supported.
  • Get equivalencies – takes a session token and returns classifier reported equivalent concepts.
  • Get new/old/unchanged inferred relationships – reports on the inferred relationships resulting from classification. New relationships need to be added, old relationships need to be retired (or removed) and unchanged inferred relationships are available merely for reporting.
  • Compare concepts – takes two concepts and compares them returning a “validation result” detailing the differences. This method is essentially used for conflict analysis and is very similar to how map records are compared within the mapping tool. Resolution of the conflict is entirely up to the application.

TODO: rewrite, add examples

  • n/a