CdmRestServices » History » Revision 26
« Previous |
Revision 26/45
(diff)
| Next »
Andreas Müller, 07/15/2008 03:17 PM
- Table of contents
- CDM REST Services
CDM REST Services¶
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:
Accept HTTP request header #sec14.1 - Accepted mime types are:
application/json@, @text/xml
Accept-Language #sec14.4
Accept-Charset #sec14.2
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 TDO 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:
Cichorieae: http://search.biocase.org:8080/cdmserver-cichorieae/
Diptera: http://search.biocase.org:8080/cdmserver-cichorieae/
Palmae: unavailable
Reference Implementation¶
The CDM Data Portal, as a central component of the CommunityWebsites of the 'EDIT Platform for Cybertaxponomy' , is using the CDM REST Services for online publishing of taxonomic treatments. If your 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:
- uuid: the uuid of a source:trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/name/TaxonNameBase.java object
Returns: A source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/NameTO.java
taxon/{uuid}¶
Arguments:
- uuid: the uuid of a source:trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/taxon/TaxonBase.java object
Returns: A source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/TaxonTO.java
ref/{uuid}¶
Arguments:
- uuid: the uuid of a source:trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/taxon/TaxonBase.java object
Returns: A source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/RefrenceTO.java
simple/name/{uuid,..}¶
Arguments:
- uuid,..: A single uuid of a source:trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/taxon/TaxonNameBase.java object or a comma separated list of uuids
Returns: A list of source:trunk/cdmlib/cdmlib-remote/src/main/java/eu/etaxonomy/cdm/remote/dto/NameSTO.java
simple/taxon/{uuid,..}¶
Arguments:
- uuid,..: A single uuid of a source:trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/taxon/TaxonBase.java object or a comma separated list of uuids
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:
- uuid,..: A single uuid of a source:trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/taxon/TaxonBase.java object or a comma separated list of uuids
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:
- uuid,..: As single uuid of a source:trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/taxon/ReferenceBase.java object or a comma separated list of uuids
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:8080/cdmserver-cichorieae/find/taxon/Lapsana+communis?onlyAccepted=0&page=1&pagesize=15&mode=BEGINNING http://search.biocase.org:8080/cdmserver-cichorieae/find/taxon/%2Asana+com%2A?onlyAccepted=0&page=1&pagesize=20&mode=ANYWHERE [This request uses the asterisk '*' as wildcard wuich is URI-encoded and thuis appears as %2 in the URI] http://search.biocase.org:8080/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:
- uuid: The uuid of a source:trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/taxon/TaxonBase.java object
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:
- uuid: The uuid of a source:trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/taxon/TaxonBase.java object
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 Andreas Müller about 16 years ago · 26 revisions