Data services

The registry of the Atlas of Living Australia maintains metadata that describe:

  • collections - natural history collections;
  • institutions - institutions and organisations that manage collections;
  • dataProviders - providers of biodiversity information in electronic form, eg occurrence records, websites;
  • dataResources - specific resources made available by data providers;
  • tempDataResources - temporary resources holding records uploaded to the sandbox;
  • dataHubs - aggregators of biodiversity data; and
  • contacts - for any of the above resources.

Access to this metadata is provided by resource-oriented web services that adhere to RESTful principles. Response payloads are generally formatted as JSON although some services offer other formats through content negotiation.

Details of how these services can be used are provided at the project's wiki, and in particular here.

Form of URIs

All service URIs are based on the URI of this page: http://collections.ala.org.au/ws
URI's for the resources listed above are this root plus the name of the type of resource, eg: http://collections.ala.org.au/ws/institution
The URI for a specific instance of a resource is the same followed by the UID of the instance. For example, the resource representing the Aust. Wine Research Institute (UID=in72) is: http://collections.ala.org.au/ws/institution/in72
The URI to get a total count of a specific resource is resource name followed by 'count'. For example, the number of institutions is given by: http://collections.ala.org.au/ws/institution/count
Counts for a specific resource can be grouped by any attribute of the resource. For example, the breakdown of institutions by state is given by: http://collections.ala.org.au/ws/institution/count/state
Resources that are attributes of a resource, such as the list of contacts for a collection, are addressed by appending the resource type to the uri that represents the main resource, eg: http://collections.ala.org.au/ws/institution/in72/contacts

Methods

Data services support the GET, HEAD, POST, PUT, OPTIONS and DELETE methods.

GET will return the json representation of the specified resource or the list of all resources of the specified resource type.

HEAD will return no content but will confirm the existence of the specified resource.

POST will update the specified resource based on the information in the body of the request. If no resource is specified, the information in the body will be used to create a new resource. The body must be valid json and you must specify at least these properties:

  • user - the name of the application that is requesting the update; and
  • api_key - a valid key to verify that you are authorised to modify the resource.

If a new resource is being created you must also specify at least:

  • name - the name of the resource

Other properties are treated as the properties to be updated. Property names are the same as those used in the GET representation.

PUT behaves the same as POST.

OPTIONS returns a list of the allowed methods.

DELETE will remove the specified resource. The body must be valid json and you must specify these properties:

  • user - the name of the application that is requesting the update; and
  • api_key - a valid key to verify that you are authorised to modify the resource.

Contacts

Contacts exist as resources in their own right. They can be accessed in the standard form.

List all contacts: http://collections.ala.org.au/ws/contacts
Get details for a specific contact http://collections.ala.org.au/ws/contacts/31
Find a contact by its email address http://collections.ala.org.au/ws/contacts/email/dave.martin@csiro.au

Editing contacts follows the same pattern as the major entities. PUT and POST will update a contact if an id is specified in the url, else a new contact is added. DELETE will remove a contact.

The body must be valid json and you must specify at least these properties:

  • user - the name of the application that is requesting the update; and
  • api_key - a valid key to verify that you are authorised to modify the resource.

and may also specify

  • firstName
  • lastName
  • fax
  • phone
  • mobile
  • notes
  • public (true or false) - controls whether the contact will be displayed on a public web page

Note that contacts do not have UIDs. They use the raw DB-assigned ID instead.

The user's email is effectively the primary key for a contact. Always check whether a contact exists (by searching for its email address) before creating one.

Contact relationships

A contact may be associated with any number of resources. A resource may have any number of contacts. The relationship between a contact and a resource has its own metadata such as the role that the contact has in relation to the resource, the contact's editing rights, etc.

This metadata is accessed by appending contacts to the uri of a resource using the form:
GET http://collections.ala.org.au/ws/{resource type}/{resource uid}/contacts
For example: http://collections.ala.org.au/ws/collection/co13/contacts
The metadata for a specific contact relationship has the form:
GET http://collections.ala.org.au/ws/{resource type}/{resource uid}/contacts/{id}
For example: http://collections.ala.org.au/ws/collection/co13/contacts/20
The primary contacts for all instances of a type of resource can be accessed using the form:
GET http://collections.ala.org.au/ws/{resource type}/contacts
For example: http://collections.ala.org.au/ws/collection/contacts
Contacts may elect to be notified when significant events occur to a resource. The list of contacts to be notified for a specific resource can be retrieved from a uri of the form:
GET http://collections.ala.org.au/ws/{resource type}/{resource uid}/contacts/notifiable
For example: http://collections.ala.org.au/ws/collection/co13/contacts/notifiable
You can retrieve all the entities that the specified contact is authorised to edit. The uri has the form:
GET http://collections.ala.org.au/ws/contacts/{contact id}/authorised
For example: http://collections.ala.org.au/ws/contacts/132/authorised

All contact services can return payload as CSV, XML or JSON via content negotiation.
More information.

Contact relationships can be updated by following the usual rules. The contact must already exist.

POST will add the contact to a resource if it does not already exist or will update the relationship using the json data in the request body.

The body must be valid json and you must specify at least these properties:

  • user - the name of the application that is requesting the update; and
  • api_key - a valid key to verify that you are authorised to modify the resource.

and may also specify

  • role - the role the contact has in for this resource eg, 'Manager'
  • notify (true or false) - if the contact wishes to be notified on significant events (this has been superceded by Alerts)
  • administrator - if the contact is allowed to administer this resource
  • primaryContact - if the contact is the primary contact for this resource

The form of the url is http://collections.ala.org.au/ws/{resource type}/{resource uid}/contacts/{contact id}

PUT same as POST.

DELETE will remove the contact from a resource.

The body must be valid json and you must specify at least these properties:

  • user - the name of the application that is requesting the update; and
  • api_key - a valid key to verify that you are authorised to modify the resource.

The url has the same form as above.

EML metadata interchange

The registry provides a service to extract resource metadata in EML format. The response complies with GBIF's EML schema. This document is suitable for inclusion in a Darwin Core Archive as the metadata description of the contained records. The form is:

GET http://collections.ala.org.au/ws/eml/{uid}
This example uri returns an XML document describing the set of occurrence records for the DECCW Atlas of NSW Wildlife: http://collections.ala.org.au/ws/eml/dr368

Citation services

Citation services return attribution and licence information for digitised records that can be accessed through the Atlas.

Citations for a list of data providers

This service accepts a list of entity UIDs and returns citation information for each entity. Any entity types can be specified but only data resources have meaningful citation information. For each entity, the service returns the name of the entity, its citation text, its rights text and a 'more information' string containing a link to the collectory page for the entity. The form is:

GET http://collections.ala.org.au/ws/citations/{listOfUIDs}
where listOfUIDs is a comma-separated list of UID.
This example uri returns a list of citations for the three specified data resources: http://collections.ala.org.au/ws/citations/dr368,dr105,dr357

The service can return the information as a JSON list or a CSV or TSV file with appropriate headers. The format is specified by http content-negotiation.
More information.

Lookup services

These services explicitly support inter-operation with other components of the Atlas such as the bio-cache and the BIE. They do not all comply with RESTful principles but are being progressively refactored to do so.

Map a bio-cache record to a collection

This service takes a collection code and an institution code from a raw specimen record and maps the combination to a single collection. The form is:

GET http://collections.ala.org.au/lookup/inst/{institution-code}/coll/{collection-code}
This example uri returns metadata for the Australian National Insect Collection: http://collections.ala.org.au/lookup/inst/ANIC/coll/Insects
More information.

Get a summary for an entity

This service just returns a subset of metadata for an entity. The form is:

GET http://collections.ala.org.au/lookup/summary/{uid}
This example uri returns the short metadata for the Birds Australia data provider: http://collections.ala.org.au/lookup/summary/dp28

The summary services are less useful now that we have full RESTful metadata services but are retained for backward compatibility. They also provide a small efficiency when the service is called repeatedly such as during indexing operations. More information.

Lookup the name of an entity

This service is even more cut down than the summary. It returns only the name of an entity given its UID. The form is:

GET http://collections.ala.org.au/lookup/name/{uid}

More information.

Get taxonomic coverage hints for an entity

This service plays a roll in taxonomic name matching during the processing of raw bio-cache records. When a record has been mapped to a collection, the collection metadata can be used to inform the matching process by adding weight to matches within particular taxonomic groups. The form is:

GET http://collections.ala.org.au/lookup/taxonomicCoverageHints/{uid}
This example uri returns a list of rank-name pairs that describe a taxonomic range: http://collections.ala.org.au/lookup/taxonomyCoverageHints/co12
More information.

List download limits for all data resources

Limits can be applied to the number of records that can be downloaded from a particular resource per request. If [ ] is returned, there are no limits currently set. The form is:

GET http://collections.ala.org.au/lookup/downloadLimits

Generate UID for a new entity

This is a temporary service used when new data resources are discovered during the harvesting of records. This service will disappear when the harvesting process is refactored. The standard data services will be used to create the new resource and return the UID assigned by the collectory. The form is:

GET http://collections.ala.org.au/lookup/generateDataResourceUid

More information.