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

This wiki page is a draft 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.

• Table of contents
• Web Services Specification for accessing CoL Checklist from a CDM Data Source
  • General
    • Url Naming
    • Name Strings
    • Multiple query request
    • Single / Multiple response array
    • Paging
    • Name Fields
  • Web Services
    • Name String Search

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.