- HELP CONTENTS 1. SUMMARY 2. GET INDIVIDUAL RECORDS - get 3. SEARCH FOR RECORDS - list 4. COUNT RECORDS - count 5. GET HELP - help 6. RESPONSE STRUCTURE - schema 7. BROWSER FORMATTING - stylesheet 1. SUMMARY The resource web service provides access to records describing the data resources in the GBIF network. Syntax: http://crbio.cr/portalCRBio/ws/rest/resource/<action>?<parameter_list> where: action is one of: get - get a single resource record list - search for resource records matching a range of filters count - count resource records matching a range of filters help - displays this help text schema - returns the response schema document stylesheet - returns a stylesheet for rendering response documents as HTML parameter_list is a set of key-value pair options controlling or modifying how the service handles the action request. See subsections below for information on the parameters supported in parameter list for each action. 2. GET INDIVIDUAL RECORDS - get Syntax: http://crbio.cr/portalCRBio/ws/rest/resource/get/<key>?<parameter_list> or: http://crbio.cr/portalCRBio/ws/rest/resource/get?<parameter_list> where: key is a numeric key uniquely identifying the resource record within the GBIF data portal. parameter_list is a set of URL-encoded key-value pairs including any of the following keys: key - numeric key uniquely identifying the resource record within the GBIF data portal (same as key above) stylesheet - sets the URL of the stylesheet to be associated with the response document. This overrides the default provided by the data portal. Supplying an empty string as the value for this parameter disables the setting of a stylesheet by the data portal. The value of this parameter is used in an xml-stylesheet processing instruction at the start of the response document. See "7. BROWSER FORMATTING - stylesheet" below. The get action is intended as a quick way to retrieve a resource record for which the key is already known (e.g. from an earlier use of the list action). The response is formatted according to the XML schema returned by the schema action (see "6. RESPONSE STRUCTURE - schema" below). The taxonConcepts element contains the taxon concepts of the highest rank found in the resource and can be used to start exploring the resource's taxonomy through the taxon web service. Examples: http://crbio.cr/portalCRBio/ws/rest/resource/get/100 - returns the resource record with key 100 http://crbio.cr/portalCRBio/ws/rest/resource/get?key=100&stylesheet= - returns the resource record with key 100 with HTML formatting disabled. 3. SEARCH FOR RECORDS - list Syntax: http://crbio.cr/portalCRBio/ws/rest/resource/list?<parameter_list> where: parameter_list is a set of URL-encoded key-value pairs including any of the following keys: name - return only resources with names starting with the supplied string. providerkey - return only resources served by the provider identified by the supplied key. Values for this key may be retrieved via previous calls to the provider, resource or occurrence web services. basisofrecordcode - return only resources which are identified as serving data with the identified basis of record. Note that this only checks the default basis of record for the resource. Supported values are: specimen, observation, living, germplasm, fossil, unknown. modifiedsince - return only records which have been indexed or modified in the GBIF data portal index on or after the supplied date (format YYYY-MM-DD, e.g. 2006-11-28). Note that these dates are based on the time at the GBIF Secretariat in Copenhagen. startindex - return the subset of the matching records that starts at the supplied (zero-based index). If this is not supplied, the response includes records starting with the first matching record (equivalent to startindex=0). This can be used in conjunction with information in the /gbifResults/header/summary element in the response document to manage paging through large sets of records. maxresults - return at most the specified number of records. The default (and maximum supported) is 1000 records. stylesheet - sets the URL of the stylesheet to be associated with the response document. This overrides the default provided by the data portal. Supplying an empty string as the value for this parameter disables the setting of a stylesheet by the data portal. The value of this parameter is used in an xml-stylesheet processing instruction at the start of the response document. See "7. BROWSER FORMATTING - stylesheet" below. The list action should be used to find resource records of interest from within the GBIF data portal. Note that this action does not count all records in the portal matching the supplied filters. The totalMatched attribute in the response should only be used to indicate whether further records exist. To get an accurate total count, us the count action (see "4. COUNT RECORDS - count" below). The response is formatted according to the XML schema returned by the schema action (see "6. RESPONSE STRUCTURE - schema" below. The resource records are found in the response document at the path /gbifResponse/dataProvider/dataProvider The /gbifResponse/header/summary element may contain up to four attributes: start - the index of the first matching record returned. totalMatched - the minimum number of matching records contained in the portal. This should only be used to indicate that there are more records still unreturned. Use the count action for an accurate count. This value is only reliable if the startindex on the request was lower than the number of records actually matching. totalReturned - the number of records actually returned in this response. next - the index of the next matching record (if totalMatched is greater than totalReturned). This can be used as the value for startindex on the next list request to retrieve another page of matching records. When there are more matching records to retrieve (i.e. the next attribute is set), the document includes a URL which can be used to retrieve the next page. This is returned in the /gbifResponse/header/nextRequestUrl element. Examples: http://crbio.cr/portalCRBio/ws/rest/resource/list?name=Can - returns records for resources with names beginning with the string "Can" http://crbio.cr/portalCRBio/ws/rest/resource/list?basisofrecordcode=germplasm - returns records for resources containing germplasm data. Likely future enhancements: 1. Support multiple values for a single parameter (to be OR'ed together). 4. COUNT RECORDS - count Syntax: http://crbio.cr/portalCRBio/ws/rest/resource/count?<parameter_list> where: parameter_list is a set of URL-encoded key-value pairs including any of the following keys: name - count only resources with names starting with the supplied string. providerkey - count only resources served by the provider identified by the supplied key. Values for this key may be retrieved via previous calls to the provider, resource or occurrence web services. basisofrecordcode - count only resources which are identified as serving data with the identified basis of record. Note that this only checks the default basis of record for the resource. Supported values are: specimen, observation, living, germplasm, fossil, unknown. modifiedsince - count only records which have been indexed or modified in the GBIF data portal index on or after the supplied date (format YYYY-MM-DD, e.g. 2006-11-28). Note that these dates are based on the time at the GBIF Secretariat in Copenhagen. stylesheet - sets the URL of the stylesheet to be associated with the response document. This overrides the default provided by the data portal. Supplying an empty string as the value for this parameter disables the setting of a stylesheet by the data portal. The value of this parameter is used in an xml-stylesheet processing instruction at the start of the response document. See "7. BROWSER FORMATTING - stylesheet" below. The count action can be used to get an accurate count of resource records of interest from within the GBIF data portal prior to retrieving these records using the list action. This may assist with deciding whether to refine the search more closely before retrieving records. The response is formatted according to the XML schema returned by the schema action (see "6. RESPONSE STRUCTURE - schema" below). The count is returned in the totalMatched attribute of the /gbifResponse/header/summary element in the response document. Examples: http://crbio.cr/portalCRBio/ws/rest/resource/count?providerkey=8 - counts resources served by provider 8 Likely future enhancements: 1. Support multiple values for a single parameter (to be OR'ed together). 5. GET HELP - help Syntax: http://crbio.cr/portalCRBio/ws/rest/resource/help or: http://crbio.cr/portalCRBio/ws/rest/resource The help action returns this help documentation. 6. RESPONSE STRUCTURE - schema Syntax: http://crbio.cr/portalCRBio/ws/rest/resource/schema The schema action returns the XML schema document used for the responses to the get, list, count and help actions. The response document includes a header which includes intellectual property statements, information on the request issued and a summary of the response contents. The body of the document for the response to a list or get action request is a dataProviders element, containing one or more dataProvider elements, each with metadata on a particular provider and a dataResources element, containing one or more dataResource elements, each with metadata on a particular resource. In responses to the get action, the taxonConcepts element contains the taxon concepts of the highest rank found in the resource and can be used to start exploring the resource's taxonomy through the taxon web service. 7. BROWSER FORMATTING - stylesheet Syntax: http://crbio.cr/portalCRBio/ws/rest/resource/stylesheet The stylesheet action returns a simple XSLT document which can be used to display the responses to the get, list, count and help actions in a readable form in a web browser. An xml-stylesheet processing instruction referenceing this stylesheet is included by default in the responses to these actions. - help - This document contains data shared through the GBIF Network - see http://data.gbif.org/ for more information. All usage of these data must be in accordance with the GBIF Data Use Agreement - see http://www.gbif.org/DataProviders/Agreements/DUA - http://www.crbio.cr/portalCRBio/ws/rest/resource/stylesheet