• Table of contents
• CDM REST Services 2.0
  • Service Sections
  • Object Boundaries
  • Content Negotiation
  • Localization
  • Character Encoding
  • Service Descriptions
    • API REST service
  • Portal REST Service

CDM REST Services 2.0¶

The CDM REST Services are a web based interface to resources stored in a CDM Community Server. 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 will be available in the near future.

In contrast to the former CDM REST Services 1.0 the new architecture directly exposes domain model entities. Whereas the version 1.0 still was build using the DTO/Assembler pattern the new implementation provides direct serializations of the objects as they are stored in the CDM where ever possible. For the external representations, like LSIDs and TDWG data exchange schema like TCS however using DTOs is unavoidable. Now for the API Service there is no longer a difference between the data model used to store and manage CDM objects and another one used to transfer them to web based clients. Thereby it has become much easier to use the web service. The same account also for the Portal Service except that this service adds some fields like localized representations and to the pure CDM entities.

Service Sections¶

The CDM REST Services architecture is functionally separated into tree 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 Portal Taxonomy Service delivering the taxonomic classification tree.

• The External Service services supporting non CDM applications and services like for example a map generation service, LSID Services.

Detailed descriptions of the services are available 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. Asssociated objects of the requested object which are at the many side of the *toMany relations are available through URIs wich map the fieldname of the *toMany relation. Transient fields are not serialized.

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 to about ten levels for specific branches.

The extend of objects, i.e the initialization depth of CDM entities is documented in the ServiceDescriptions below. The extend id explained using a special 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 _

Developer Hints

The initialization od CDM entities is performed by implementations of the source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/persistence/dao/BeanInitializer.java Interface.

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 #sec14.1 - Accepted mime types are: application/json@, @text/xml

3. Default: XML

The CDM REST Services 2.0 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:

• source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/controller/interceptor/ContentNegociationHandlerInterceptor.java

Configuration in:

• source:trunk/cdmlib/cdmlib-remote/src/main/webapp/WEB-INF/cdmrest-servlet.xml#L24

Localization¶

I order to provide the client with localized resources some services respect the Accept-Language HTTP header #sec14.4.

For example the Portal service returns localized representations according to the Language tags supplied in the Accept-Language HTTP header. For each single CDM entity having language dependent representation (see: source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/model/common/Representation.java or source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/model/common/MultilanguageText.java)

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 source:trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/common/Language.java#L126 and if necessary further falls back to return the first representation found if any exists.

Please see below for detailed information on how and whether localization is handled by the different service sections.

Developer Hints

Classes involved in Content Negotiation:

• source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/controller/interceptor/LocaleContextHandlerInterceptor.java

Configuration in:

• -- not necessary --

Character Encoding¶

All data is returned in UTF-8 character encoding.

Service Descriptions¶

API REST service¶

e.g.

taxonService.get(UUID uuid)

and

GET /taxon/{uuid}

Following from that logic, the listing methods should work thus

taxonService.list(Class<? extends TaxonBase> clazz, Integer page, Integer limit, etc)

and the URI would be

GET /taxon?page=X&limit=Y&clazz=Z

Portal REST Service¶