REST API

The CDM REST API is a RESTful interface to resources stored in the CDM. The RESTful architecture allows accessing the various resources like Taxa, Names, References, Media, etc by stable URIs. Due to security constraints and to assure the integration of data, currently only read operations (= HTTP GET) are permitted, write operations may become available in the future.

The architecture directly exposes domain model entities, i.e. it provides direct serializations of the objects as they are stored in the CDM whereever possible. For the external representations, like LSIDs and TDWG data exchange schema like TCS however using DTOs is unavoidable. The API Service provides an easy to use way to transfer CDM data to web based clients. The Portal Service is a specialization as needed by CDM Dataportal that adds some fields like localized representations to the pure CDM entities.

Table of Contents

Service Sections

The CDM REST Services architecture is functionally separated into four different parts:

  • The API Service a clean RESTful bit, which will expose data in a modular, normalized way. It is a more-or-less one-to-one concordance between URIs and service api methods.
  • The Portal Service which is specially taliored for the needs of dataportals which will primarily display "Species Page". Thus this service will be provide denormalized pages which contain a specific assemblys of information.
  • The External Services are supporting non CDM applications and services like for example a map generation service, LSID Services.
  • The Classification Service exposes special DTOs which combine data from the TaxonBase, TaxonNode and from the Classification entities.

Detailed descriptions of the services are available in Service Descriptions below.

Object Boundaries

Nearly all CDM entities are related to each other more or less dicrectly or indirectly and thus forming a huge object graph. A web services however should only deliver a specific object perhaps with some attached associated objects, so it id crucial to draw the line quite sensible between the objects in question and the full object graph. The CDM Service solves this by selectively initializing CDM entities.

The primary idea is that the API Service delivers the requested object with all its *toOne relations. Associated objects of the requested object which are at the many side of the *toMany relations are available through URIs which map the fieldname of the *toMany relation. Transient fields are not serialized except of the titleCache property, this one and serialized and thus initialized for each IdentifiableEntity. The initialization of the titleCache property is performed by the CacheStrategie of the specific cdm class and usually spans multiple associated entities of variable depth of object nesting.

In contrast the Portal Service, often adds *toMany relations and transient fields to the requested objects. It even may deliver sub object graphs with a depth of an arbitrary number of levels for specific branches.

The extend of objects, i.e the initialization depth of CDM entities is documented in Service Descriptions below. The extend is explained using a property path syntax which indicates the properties and transient getters of a specific CDM entity bean which are being initialized by the service.

  • Simple (name) - The specified name identifies an individual property of a particular CDM entity bean. The name of the actual getter method is determined using standard !JavaBeans instrospection, so that a property named "xyz" will have a getter method named getXyz() or (for boolean properties only) isXyz(), and a setter method named setXyz().
  • Nested (name1.name2.name3) The first name element is used to select a property getter, as for simple references above. The object returned for this property is then consulted, using the same approach, for a property getter for a property named name2, and so on. The property value that is ultimately retrieved or modified is the one identified by the last name element.
  • Indexed (name[index]) - The underlying property value is assumed to be an array, or this !JavaBean is assumed to have indexed property getter and setter methods. The appropriate (zero-relative) entry in the array is selected. List objects are now also supported for read/write. You simply need to define a getter that returns the List
  • *toOne-Wildcard ($) This wildcard is used to select all property getters which reference to one associated bean. A wildcard subsequently terminates a 'property path'.
  • *toAny-Wildcard (*) This wildcard is used to select all property getters which reference to one associated bean and to to many associated bean. A wildcard subsequently terminates a 'property path'.
  • Combined (name1.name2[index].$) - Combining mapped, nested, and indexed and wildcard references is also supported.

This syntax description partially is lend from Apache Commons BeanUtils

In fact the actual extend of serialized CDM entities may exceed the extend indicated by the property path syntax. This especially happens when a transient getter is to be initialized. Due to potential internal logic in the transient getter it is unpredictable which properties actually are being initialized when only looking at the property path. A common candidate for this is the getTaggedName() property of TaxonNameBase.

Developer Hints:

The initialization od CDM entities is performed by implementations of the BeanInitializer interface. In order to find out more on this topic please refer to CDM Entity Initialization.

Localization

In order to provide the client with localized resources all services respect the Accept-Language HTTP header. For example the Portal service returns localized representations according to the Language tags supplied in the Accept-Language HTTP header. The service tries finding the best matching representation. If no representation in any preferred language is found the service falls back to return the representation in Default Language and if necessary further falls back to return the first representation found if any exists.

Instances of the folowing CDM classes or subclasses of them potentially have multiple internationalized representations in different languages:

  • TermBase - language dependent representation through Representation; The localized reresentation string is added to the TermBase entities by adding the aaditional field: representation_L10n.
  • TextData - language dependent representation through MultilanguageText; The localized multilanguage text string is added to the TextData entities by adding the aaditional field: multilanguageText_L10n.

Localization is handled a bit differently by various service sections the API Service just adds the localized representations. The Portal Service which focuses in representation, not only adds the localized representations but also hides the Representation or MultilanguageText fields from serialization in order to reduce complexity and to improve performance.

Developer Hints

Classes involved in Content Localization:

Content Negotiation

There are two ways to demand a special content type:

  1. by file extension (*.json or *.xml)
  2. by Accept HTTP request header - Accepted mime types are: application/json, text/xml

Default: XML

The CDM REST API primarily trys using the file extension, then the Accept HTTP request header is taken into account. If whether the file extension or not the Accept HTTP request header specify valid content types the default XML will be used.

Developer Hints

Classes involved in Content Negotiation:

Configuration files involved:

Character Encoding

All data is returned in UTF-8 character encoding.

Service Descriptions

The syntax of the mapped service URIs contains the the {datasource-bean-name} path element. The available {datasource-bean-name}s are taken from a configuration file which is loaded by the CDM-Server during startup. The "datasources.xml" file is loaded by default from the following locations depending on the operation system in which the cdm-server is installed:

  • Linux: /opt/cdm-server/.cdmLibrary/datasources.xml
  • Windows: "%PROGRAMFILES%/EDIT CDM-Server/.cdmLibrary/datasources.xml"

The actual location of the "datasources.xml" can specified and thus be overridden using a specific commandline parameter for EDIT CDM-Server. For more information please refer to the CDM Community Server documentation.

NOTE:

  1. Former versions of the EDIT CDM-Server where using {USER_HOME}./cdmLibrary/datasources.xml this is now being only used by the EDIT Taxonomic Editor.
  2. The UpdatableRoutingDataSource is no longer being used by the EDIT CDM-Server.

API Service

These are a clean RESTful webservices, which will expose data in a modular, normalized way. It is a more-or-less one-to-one concordance between URIs and service api methods. Due to its generic architecture the URIs are also generic and follow a common pattern which is repeated in each controller. In the following the generic URIs are documented first followed by type specific implementations. The pathelement {base-type} is frequently used in generid URIs.

Valid Values for {base-type} are:

  • agent: Service URIs returning AgentBase or sub type entities.
  • description: Service URIs returning DescriptionBase or sub type entities.
  • feature: Service URIs returning DescriptionBase or sub type entities
  • media: Service URIs returning Media or sub type entities
  • name: Service URIs returning TaxonNameBase or sub type entities
  • occurrence: Service URIs returning SpecimenOrObservationBase or sub type entities
  • reference: Service URIs returning ReferenceBase or sub type entities
  • taxon: Service URIs returning TaxonBase or sub type entities
  • term: Service URIs returning DefinedTermBase or sub type entities

Most services are using the default initialisation strategy which is:

"$"
/{base-type}/

Depending on the URI parameters used, this service returns either a Pager on or a List of the {base-type} entities identified by the {uuid}. The returned {base-type} instances are initialized by the default initialisation strategy.

URI Parameters to return a Pager:

  • pageNumber the number of the page to be returned, the first page has the pageNumber = 1 - optional parameter
  • pageSize the maximum number of entities returned per page (can be null to return all entities in a single page) - optional parameter
  • type Further restricts the type of entities to be returned. If null the type mapped by {base-type} is being used. - optional parameter

URI Parameters to return a List:

  • start The offset index from the start of the list. The first entity has the index = 0 - required parameter The start parameter is used to distinguish between the List and Pager variants!
  • limit The maximum number of entities returned. - optional parameter
  • type Further restricts the type of entities to return. If null the type mapped by {base-type} is being used. - optional parameter
/{base-type}/name/{uuid}

Get the {base-type} entity identified by the {uuid}.

Returns:

The returned {base-type} entity is initialized by the default initialisation strategy.

/{base-type}/name/{uuid}/annotation

Get the a Pager on the Annotations for the {base-type} entity identified by the {uuid}.

Returns:

Pager on the Annotations for the {base-type} entity identified by the {uuid}. The returned {base-type} entity are initialized by the default initialisation strategy.

External Service

/geo/map/distribution/{taxon-uuid}

Assembles and returns URI parameter Strings for the EDIT Map Service. The distribution areas for the Taxon instance identified by the {taxon-uuid} are found and are translated into an valid URI parameter String. Higher level distribiution areas are expanded in order to include all nested sub-areas.