EDIT

{{>toc}}

_Implementation notes are found in [[CdmRestServicesImplementationNotes]]._

----

# CDM REST Services 2.0

The CDM REST Services are a web based interface to resources stored in a [[CommunityServer|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 [[CdmRestServices1|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](http://java.sun.com/blueprints/corej2eepatterns/Patterns/TransferObject.html)  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 [[CdmRestServices2#ServiceDescriptions|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. 

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 [[CdmRestServices2#ServiceDescriptions|ServiceDescriptions]] 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](http://commons.apache.org/beanutils/commons-beanutils-1.7.0/docs/api/org/apache/commons/beanutils/PropertyUtilsBean.html) ~

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 source:"trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/name/TaxonNameBase.java".

*Developer Hints*:

The initialization od CDM entities is performed by implementations of the  source:"trunk/cdmlib/cdmlib-persistence/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)

1. by  [Accept HTTP request header](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) #sec14.1 - Accepted mime types are: `application/json@, @text/xml`    

1. Default: XML

The [[CdmRestServices2|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](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) #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

The syntax of the mapped service URIs contains the the {datasource-name} path element. The available {datasource-name}s are defined in a configuration file which is loaded by the UpdatableRoutingDataSource. By default the "datasources.xml" in @ {USER_HOME}./cdmLibrary @ is being used (for details please refer to [[WebserviceDeployment]]). If the UpdatableRoutingDataSource is not being used in the actual application context, any arbitrary {datasource-name} may be used.

### API Service

The are a clean RESTful webservice, 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.

In the URIs the pathelement {base-type} is used sometimens.

_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:

~~~

"$"

~~~

#### /{datasource-name}/{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 following strategy: DEFAULT_INIT_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 {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 base type <T> is being used. - _optional parameter_ 

#### /{datasource-name}/{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. 

####  /{datasource-name}/{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.

### Portal Service

#### /{datasource-name}/portal/name/{name-uuid}

The TaxonNameBase instance identified by the {name-uuid}. 

The returned TaxonNameBase is initialized by the following strategy 

~~~

~~~

#### /{datasource-name}/portal/name/{name-uuid}/descriptions

Get the list of TaxonNameDescriptions of the Name associated with the TaxonNameBase instance identified by the {name-uuid}.

_Returns:_

a List of TaxonNameDescription entities which are initialized using the following initialization strategy:

~~~

"uuid",

"feature",

"elements.$",

"elements.multilanguageText",

"elements.media.representations.parts"

~~~

#### /{datasource-name}/portal/name/{name-uuid}/typeDesignations

Get the list of TypeDesignationBases of the TaxonNameBase instance identified by the {name-uuid}. 

_Returns:_

a List of TypeDesignationBase entities which are initialized using the following initialization strategy:

~~~

"citation.authorTeam",

"typeName.$",

"typeName.taggedName",

"typeStatus.representations",

"typeSpecimen.media.representations.parts"

~~~

#### /{datasource-name}/portal/taxon/{taxon-uuid}

Get the TaxonBase instance identified by the {taxon-uuid}. 

The returned Taxon is initialized by the following strategy TAXON_INIT_STRATEGY 

~~~

"*",

"relationsToThisName.fromTaxon.name.taggedName",

"name.$",

"name.taggedName",

"name.rank.representations",

"name.status.type.representations",

"descriptions.elements.$",

"descriptions.elements.area",

"descriptions.elements.area.$",

"descriptions.elements.multilanguageText",

"descriptions.elements.media.representations.parts",

~~~

#### /{datasource-name}/portal/taxon/find

Find Taxa, Synonyms, Common Names by name, either globally or in a specific geographic area. 

_URI Parameters:_

* **query** the string to query for. Since the wildcard character '*' internally always is appended to the query string, a search always compares the query string with the beginning of a name. - _required parameter_

* **treeUuid** the UUID of a TaxonomicTree to which the search is to be restricted. - _optional parameter_

* **areas** restrict the search to a set of geographic NamedAreas. The parameter currently takes a list of TDWG area labels.  - _optional parameter_

* **page** 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_

* **doTaxa** weather to search for instances of Taxon - _optional parameter_

* **doSynonyms** weather to search for instances of Synonym - _optional parameter_

* **doTaxaByCommonNames** for instances of Taxon by a common name used - _optional parameter_

_Returns:_

a pager on a list of IdentifiableEntitys initialized by the following strategy:

~~~

"*",

"relationsToThisName.fromTaxon.name.taggedName",

"name.$",

"name.taggedName",

"name.rank.representations",

"name.status.type.representations"

~~~

#### /{datasource-name}/portal/taxon/{taxon-uuid}/synonymy

Get the synonymy for a taxon identified by the {taxon-uuid}. The synonymy consists of two parts: The group of homotypic synonyms of the taxon and the heterotypic synonymy groups of the taxon. The synonymy is ordered historically by the type designations and by the publication date of the nomenclatural reference 

_Returns:_

a Map with to entries which are mapped by the following keys: "homotypicSynonymsByHomotypicGroup", "heterotypicSynonymyGroups", containing lists of Synonyms which are initialized using the following initialization strategy:

~~~

"synonymRelations.$",

"synonymRelations.synonym.$",

"synonymRelations.synonym.name.taggedName",

"synonymRelations.synonym.name.nomenclaturalReference.inBook.authorTeam",

"synonymRelations.synonym.name.nomenclaturalReference.inJournal",

"synonymRelations.synonym.name.nomenclaturalReference.inProceedings",

"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.$",

"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.name.taggedName",

"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.$",

"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName",

"name.homotypicalGroup.$",

"name.homotypicalGroup.typifiedNames.$",

"name.homotypicalGroup.typifiedNames.name.taggedName",

"name.homotypicalGroup.typifiedNames.taxonBases.$",

"name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName"

~~~

#### /{datasource-name}/portal/taxon/{taxon-uuid}/accepted

Get the list of accepted Taxon entities for a given TaxonBase instance identified by the {taxon-uuid}. 

_URI Parameters:_

* **page** the number of the page to be returned, the first page has the pageNumber = 1

* **pageSize** the maximum number of entities returned per page (can be null to return all entities in a single page)

 _Returns:_

a Pager on a list of Taxon entities which are initialized using the following initialization strategy:

~~~

"synonymRelations.$",

"synonymRelations.synonym.$",

"synonymRelations.synonym.name.taggedName",

"synonymRelations.synonym.name.nomenclaturalReference.inBook.authorTeam",

"synonymRelations.synonym.name.nomenclaturalReference.inJournal",

"synonymRelations.synonym.name.nomenclaturalReference.inProceedings",

"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.$",

"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.name.taggedName",

"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.$",

"synonymRelations.synonym.name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName",

"name.homotypicalGroup.$",

"name.homotypicalGroup.typifiedNames.$",

"name.homotypicalGroup.typifiedNames.name.taggedName",

"name.homotypicalGroup.typifiedNames.taxonBases.$",

"name.homotypicalGroup.typifiedNames.taxonBases.name.taggedName"

~~~

####  /{datasource-name}/portal/taxon/{taxon-uuid}/taxonRelationships

Get the list of TaxonRelationships for the given TaxonBase instance identified by the {taxon-uuid}. 

_Returns:_

a List of TaxonRelationship entities which are initialized using the following initialization strategy:

~~~

"$",

"type.inverseRepresentations",

"fromTaxon.sec.authorTeam",

"fromTaxon.name.taggedName"

~~~

#### /{datasource-name}/portal/taxon/{taxon-uuid}/nameRelationships

Get the list of NameRelationships of the Name associated with the TaxonBase instance identified by the {taxon-uuid}. 

_Returns:_

a List of NameRelationship entities which are initialized using the following initialization strategy:

~~~

"$",

"type.inverseRepresentations",

"fromName.taggedName"

~~~

#### /{datasource-name}/portal/taxon/{taxon-uuid}/nameTypeDesignations

Get the list of TypeDesignationBases of the TaxonBase instance identified by the {taxon-uuid}. 

_Returns:_

a List of TypeDesignationBase entities which are initialized using the following initialization strategy:

:

~~~

"typeSpecimen.$",

"typeStatus.representations",

"citation.authorTeam",

"typeName.taggedName"

~~~

#### /{datasource-name}/portal/taxon/{taxon-uuid}/descriptions

Get the list of TaxonDescriptions of the Taxon instance identified by the {taxon-uuid}. 

_Returns:_

a List of TaxonDescription entities which are initialized using the following initialization strategy:

~~~

"$",

"elements.$",

"elements.citation.authorTeam",

"elements.multilanguageText",

"elements.media.representations.parts"

~~~

#### /{datasource-name}/portal/name/{taxon-uuid}/media/{mime type list}/{size}[,[widthOrDuration}][,{height}]/ 

Get the list of TaxonDescriptions of the Taxon instance identified by the {taxon-uuid}. 

_Usage:_

 /{datasource-name}/portal/name/{taxon-uuid}/media/{mime type list}/{size}[,[widthOrDuration}][,{height}]/ 

_Whereas_ 

* *{mime type list}*: a comma separated list of mime types, in the order of preference. The forward slashes contained in the mime types must be replaced by a colon. Regular expressions can be used. Each media associated with this given taxon is being searched whereas the first matching mime type matching a representation always rules. 

* *{size}*,*{widthOrDuration}*,*{height}*: (not jet implemented) valid values are an integer or the asterisk '*' as a wildcard 

_Returns:_

a List of Media entities which are initialized using the following initialization strategy:

~~~

"$",

"elements.$",

"elements.citation.authorTeam",

"elements.multilanguageText",

"elements.media.representations.parts"

~~~

### Portal Taxonomy Service

### External Service