/
REST Content Service

REST Content Service

Owned by bcarlsen (Unlicensed)
Last updated: Mar 24, 2015

Overview

Documents the REST Content 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

This is the core service of the terminology server and supports read and write access to the range of model objects. The internal API has individual calls for each model object allowing them to be looked up either by terminology id or internal id, or to be changed using add, update, and remove methods. Additionally it supports paging/sorting/filtering access to search results based on either text queries or semantic criteria (such as having relationships to a certain destination concept – or its descendants).

The REST API for the content service authorizes the users call and exposes these internal services with some additional functionality. When reading objects, the depth of the graph that is read and returned is based on a configurable graph resolver that by default reads a concept to include its descriptions and relationships.

When creating new model objects, a configurable graph resolver is used to interconnect objects within a passed-in graph so that they can be properly managed by the JPA framework. In particular, a passed in concept containing descriptions and relationships needs to be reconnected so that the descriptions and relationships directly reference corresponding concept. This is necessary because objects are doubly linked meaning that simple containment of a description in a concept is not sufficient, the description object itself needs to then be connected back to the concept.

Additionally, a configurable identifier assignment algorithm is used to assign terminology ids as desired. Typical options would include letting the application manage assignment, using UUID-based hashes of identity fields, or simply leaving identifiers blank for later release-time assignment.

Support only access by terminology id.

The following is a summary of the REST API functionality available in this service

  • For each model object (concept, description, relationship, etc.)

    • Add/remove/update

    • Get (by managed id)

    • Get (by terminology id)

  • Clear/compute transitive closure

    • Takes a “root” node and computes transitive closure from that starting point

  • Get ancestors – based on a root node and terminology

  • Get descendants – based on a root node and terminology

  • Add concepts – takes a list of concepts and inserts all of them (batch import)

    • Atomic operation – entirely succeeds or entirely fails

  • Add descriptions – takes a list of descriptions and wires them to the correct concepts, which are presumed to exist, and inserts all of them

    • Atomic operation – entirely succeeds or entirely fails

  • Find concepts – with paging/sorting/filtering

    • Query based search – based around Lucene query syntax

    • Semantic based search – extension of query searching but supports the following features

      • Active vs. inactive

      • Module id

      • Ancestor (e.g. find concepts that are descendants of this)

      • Primitive vs. fully defined

      • Is source concept of a certain relationship type (with a particular destination)

      • Is destination concept of a certain relationship type (with a particular source)

      • Multiple conditions can be combined for conjunction.

      • Disjunction is supported via multiple calls

TODO: more detail, less prose, examples.

  • n/a