Project

General

Profile

Actions

This reference is deprecated.

With the release of the CDM v2.0 a new CDM REST Services architecture has become available :

CDM REST Services 2.0


CDM REST Services v1.0

The CDM REST Services are URL encoded REST services providing read operations (Write operations will be implemented in the future) on data kept in a CDM Community Server. The services response by sending JSON or XML (default) serializations of CdmDataTransferObjects.

The decision on the return type being used is based on the Accept HTTP request header as submitted by the client. In the following an overview on the request headers which are respected by the CDM REST Services is given:

CdmDataTransferObjects map in most cases quite exactly the according domain objects defined in [JavaDoc:cdmlib-model]. Since it is not always desirable to transmit a full-blown object some services deliver simplified versions of the CdmDataTransferObjects called 'Simple Data Transfer Objects'. In the following 'Data Transfer Objects' abbreviated with TO and 'Simple Data Transfer Objects' will be named STO. These abbreviations are also used as name suffix for the according source:/trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto.

All services under the path simple/ will return Lists of *STO*s and accept not only single but also comma separated list of @uuids@.

The services running under the path taxonomy/ expose the taxonomic trees which are defined in the database by the taxon relation has parent taxon. They all return lists of source:"trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TreeNode.java"s. This node object is a special data transfer object which contains very lean and basic information on the according taxon like its name and data wich is needed when reconstructing the tree.

The following services are already available:

| Path | * Returns* |
| name/{uuid} | A source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/NameTO.java |
| taxon/{uuid} | A source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TaxonTO.java |
| ref/{uuid} | A source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/RefrenceTO.java |
| simple/name/{uuid,..} | A list of source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/NameSTO.java |
| simple/taxon/{uuid,..} | A list of source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TaxonSTO.java |
| simple/taxon/acceptedfor/{uuid,..} | Hashtable of list of source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TaxonSTO.java TaxonSTO] |
| simple/ref/{uuid,..} | A list of source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/RefrenceSTO.java |
| find/taxon/{q} | A source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/RefrenceSTO.java of source:"trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TaxonSTO.java"s |
| taxonomy/root/{sec} | List of source:"trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TreeNode.java"s |
| taxonomy/parents/{uuid} | List of source:"trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TreeNode.java"s |
| taxonomy/children/{uuid} | List of source:"trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TreeNode.java"s |
| whatis/{uuid} | The class names of the domain object specified by {uuid}|

For implementation details on the service please refer to the JavaDocs:cdmlib-remote or to source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/service/ICdmService.java from the always up to date SVN repository for the currently implemented services.

Available CDM REST Services

CDM Community Servers offering CDM REST Services have been installed for the three EDIT exemplar groups from WP6:

Reference Implementation

The CDM Data Portal, as a central component of the CommunityWebsites of the 'EDIT Platform for Cybertaxonomy' , is using the CDM REST Services for online publishing of taxonomic treatments. If you like to implement your own application we recommend using the CDM Data Portal as guidance and reference on how to use the CDM REST Services.

Service API Documentation

name/{uuid}

Arguments:

Returns: A source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/NameTO.java

taxon/{uuid}

Arguments:

Returns: A source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TaxonTO.java

ref/{uuid}

Arguments:

Returns: A source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/RefrenceTO.java

simple/name/{uuid,..}

Arguments:

Returns: A list of source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/NameSTO.java

simple/taxon/{uuid,..}

Arguments:

Returns: A list of source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TaxonSTO.java

simple/taxon/acceptedfor/{uuid,..}

This service finds the accepted taxon for each of the taxa which are identified by their uuids. If the taxon specified by a uuid is itself the accepted taxon, this one will be returned. In rare cases, i.e. in case of pro parte synonyms, a taxon may have more than one accepted taxon, thus this service returns a list of accepted taxa, which mostly will contain only one object.

Arguments:

Returns: a Hashtable of lists of source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TaxonSTO.java.

simple/ref/{uuid,..}

Arguments:

Returns: A list of source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/RefrenceSTO.java

find/taxon/{p}

Searches for names of taxa whose names match the string given as argument q. In contrast all other services this service takes additional URI query parameters (see examples section below).

Arguments:

  • q: the query string. The asterisk * character can be used as wildcard

URL Parameters:

  • matchMode:

    • EXACT: only exact matches between the name and the query string ate taken into account
    • BEGINNIG: match the query string to the beginning of names
    • ANNYWHERE: any matching substring is taken as a hit.
  • pagesize : maximum number of iteme per result page

  • page: the number of page to be returned

Returns:

A source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/RefrenceSTO.java of

source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TaxonSTO.java TaxonSTO]s

Examples:

  http://search.biocase.org/cdmserver-cichorieae/find/taxon/Lapsana+communis?onlyAccepted=0&page=1&pagesize=15&mode=BEGINNING

  http://search.biocase.org/cdmserver-cichorieae/find/taxon/%2Asana+com%2A?onlyAccepted=0&page=1&pagesize=20&mode=ANYWHERE
  [This request uses the asterisk '*' as wildcard wich is URI-encoded and this appears as %2A in the URI]

  http://search.biocase.org/cdmserver-cichorieae/find/taxon/Cicerbita?onlyAccepted=0&page=4&pagesize=15&mode=BEGINNING

taxonomy/root/{sec}

Exposes the root nodes of the taxonomic concept tree for the concept reference specified by the sec parameter.

Arguments:

  • sec: The uuid of the concept reference of the taxonomic concept of interest. If this optional parameter is left out, the service will return all root nodes having at least one child taxon of all concepts. Ignoring nodes with no child has been chosen as strategy to exclude misapplied names from the tree root.

Returns: List of source:"trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TreeNode.java"s

taxonomy/parents/{uuid}

Searches the concept taxon tree for all parent taxa by walking the tree from the taxon which is referenced by the parameter uuid down to its

root. The reference taxon will also be included into the returned set of source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TreeNode.java instances. The node objects are ordered in the list from root to top.

Arguments:

Returns: List of source:"trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TreeNode.java"s

taxonomy/children/{uuid}

This service provides access to the children of the taxon referenced by the parameter uuid.

Arguments:

Returns: List of source:"trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TreeNode.java"s

whatis/{uuid}

'NOT JET FULLY IMPLEMENTED'

The whatis service returns the type

i.e. DTO class name and simplename & cdm class name and simplename of the instance referenced by the $uuid parameter.

Arguments:

  • uuid:

Returns: false if the cdm store contains no matching instance otherwise an associative array with the following key-value pairs:

  • 'cdmName': name of the cdm class as returned by Class.getName(), e.g. eu.etaxonomy.cdm.model.taxon.Taxon

  • 'cdmSimpleName': simple name of the cdm class as returned by Class.getSimpleName(), e.g. Taxon

  • 'dtoName': name of the DTO class as returned by Class.getName(), e.g. eu.etaxonomy.cdm.dto.TaxonTO

  • 'dtoSimpleName': simple name of the TDO class as returned by Class.getSimpleName(), e.g. TaxonTO

Updated by Katja Luther almost 2 years ago · 9 revisions