Project

General

Profile

Actions

Web Services Specification for accessing CoL Checklist from a CDM Data Source

This wiki page is a description of web services proposed as part of the i4Life project. This concerns specifically the services to access Catalogue of Life data from a CDM Datasource.


General

This section deals with general concepts which are valid and used throughout the document and applies to the web service implementations.

Url Naming

The url of the server targeting the CDM instance which provides the CoL data is named as the root_url (and looks like ‘my.server.com:8080/CoL’). The url corresponding to the namespace which targets the services related specifically to the name related data (which is the focus of this document) is named as base_url (and looks like ‘{root_url}/name_catalogue’)

Name Strings

Name strings should always be returned with authors included. This corresponds to the title cache field in the CDM Database.

Multiple query request

It is preferred to have multiple query parameters in the request, since the http specification allows for all query values to be reduced to a single query array (e.g

‘{root_url}/name_catalogue?query=Abies alba& query=Manihot esculenta’).

Single / Multiple response array

Response elements are always returned as an array of complex elements each containing a request / response pair. The single response case is taken as a special case where an array with a single complex element is returned.

Paging

All requests have an additional paging flag option. This provides the possibility to get the response in simple or paged format. This would look like ‘{root_url}/name_catalogue?query=…..&pager=[true|false]’. The default is false. In the case of paged results, the response is wrapped in a pager element. An example paged response can be seen below,

{
          "count": 439,
          "currentIndex": 5,
          "firstRecord": 126,
          "indices": [
              2,
              3,
              4,
              5,
              6,
              7
          ],
          "lastRecord": 150,
          "nextIndex": 6,
          "pageSize": 25,
          "pagesAvailable": 18,
          "prevIndex": 4,
                      "records": [ …HERE GOES THE PAGED RESULT LIST… ]
            }

Name Fields

Name fields used in the name service requests should match CDM fields as much as possible.

Web Services

This section describes the actual web service request / response pairs and provides examples for each.

Name String Search

Returns a list of all names which has the given string in its title field.

Request : Name String.

Response : List of name strings and associated name_uuids, taxon_uuids.

Namespace :

Notes : Query parameter allows for exact as well as wildcard matching.

Examples

  • Exact match

    Request :

{root_url}/name_catalogue?query=Abies alba L.
Response : 
     [    
       {
        request : 
                  {
                query : 'Abies alba L.'
                  },
        response : 
                  [
                    {                  
                      name : 'Abies alba L.',
                  name_uuids : 
                                  [
                            'ed141be3-f7c2-4472-88aa-7de899126863',
                    'ed141be3-f7c2-4472-88aa-7de899130587',
                            'ed141be3-f7c2-4472-88aa-7de899126863'
                          ],
                  taxon_uuids : [
                             'b36350de-c3c9-4ab8-b8bc-ed6190010134',
                     'b36350de-c3c9-4ab8-b8bc-ed6191010913'
                            ]
                  ]
       }
     ]
  • Wildcard match

    Request :

{root_url}/name_catalogue?query=*Abies al*
Response :
     [   
       {
        request : {
                query : '*Abies al*'
                  },
        response : 
                  [
                    {                  
                     name : 'Abies alba L.',
                 name_uuids : 
                                  [
                           'ed141be3-f7c2-4472-88aa-7de899126863',
                   'ed141be3-f7c2-4472-88aa-7de899130587',
                           'ed141be3-f7c2-4472-88aa-7de899126863'
                          ],
                 taxon_uuids : 
                                  [
                           'b36350de-c3c9-4ab8-b8bc-ed6190010134',
                   'b36350de-c3c9-4ab8-b8bc-ed6191010913'   
                          ]
                   },
                   {                   
                    name : 'Abies alberta C.M.',
                name_uuids : [
                          'ed141be3-f7c2-4472-88aa-7de899126463',
                  'ed141be3-f7c2-4472-88aa-7de897130587'                                  ],
                taxon_uuids : [
                           'b36350de-c3c9-4ab8-b8bc-ed6190013134' 
                          ]
                   }
            ]   
       }
     ]

Name Information

Returns information related to a name id.

Request : Name ID.

Response : Name related information.

Namespace : name

Notes : Also returns LSIDs contained in datasource (e.g.CoL).

Example

Request : 
{root_url}/name_catalogue/name?name_uuid=ed141be3-f7c2-4472-88aa-7de899126863
Response :
     [   
       {
         request : 
                  {
                name_uuid= 'ed141be3-f7c2-4472-88aa-7de899126863'
                  },
         response : 
                   {                  
                     name : 'Abies alba L.',
                 rank : 'Species',
             nomenclature_status : ['ILLEGITIMATE',INVALID'],          
             citation : 'Nature Journal 2006 Oct.',
                 citation_details : 'pg. 67',
                     name_relationship : 
                                        {
                       type : 'BASINONYM',
                       related_name : 'Abies originus',
                       citation : 'Biodiversity Journal 1986 Jan.'
                    },
             taxon_uuids : [
                             'b36350de-c3c9-4ab8-b8bc-ed6190010134',
                     'b36350de-c3c9-4ab8-b8bc-ed6191010913'
                           ],
                 lsid_list : [
                           "urn:lsid:catalogueoflife.org:taxon:edce3228-29c1-102b-9a4a-00304854f820:col20120124",
                                   "urn:lsid:catalogueoflife.org:taxon:edce3354-29c1-102b-9a4a-00304854f820:col20120124"
                         ]
                  }             
       }
     ]

Taxon Concept Information

Returns the taxon concept and associated names corresponding to the name id.

Request : Taxon ID.

Response : Taxon concept Info as well as related taxa ( like accepted name / synonyms ).

Namespace : taxon

Notes : Source url has been excluded for the moment as the CoL archive download does not seem to contain these. Classification information is in the form of rank-taxon name pairs for all taxa higher than the given one.

Example

Request: 
{root_url}/name_catalogue/taxon?taxon_uuid=b36350de-c3c9-4ab8-b8bc-ed6190013134
    Response :
     [ 
       {
         request : 
                   {
                 taxon_uuid= 'b36350de-c3c9-4ab8-b8bc-ed6190013134'
                   },
         response : 
                    {   
                      taxon : 
                              {     
                            name : 'Abies alberta C.M.',                             
                    taxon_status : 'synonym',
                    flags : 
                                        [
                          doubtful : 'true'
                        ],
                        classification : 
                                                 [
                                       kingdom : 'Plantae',
                           phylum  : 'Pinophyta',
                           class   : 'Pinopsida',
                           order   : 'Pinales',
                               family  : 'Pinaceae',
                           genus   : 'Abies'
                                             ]
                          },
             related_taxa : 
                                   [ 
                                     {
                           taxon_uuid : 'b36350de-c3c9-4ab8-b8bc-ed6190010134',
                                       name : 'Abies alba L.',
                       taxon_status : 'accepted name',
                                       col_url : http://www.catalogueoflife.org/....
                         },
                             { 
                               taxon_uuid : 'b36350de-c3c9-4ab8-b8bc-ed6190020314',
                                       name : 'Abies alba subsp. apennina Brullo, …..',
                                       taxon_status : 'synonym',
                           col_url : http://www.catalogueoflife.org/.... 
                                     },
                                     { 
                                       taxon_uuid : b36350de-c3c9-4ab8-b8bc-ed6191010913',
                                   name : 'Abies alba var. acutifolia Turrill',
                       taxon_status : 'synonym',
                           col_url : http://www.catalogueoflife.org/....
                                     } 
                                   ]
                    }   
       }
     ]

Updated by Andreas Müller almost 2 years ago · 23 revisions