Services

Preliminaries

Within the services documentation, some place holders are used to shorten reading and to adopt it easily to other or changing environments.

${AnnoSysURL} = https://annosys.bgbm.fu-berlin.de/AnnoSys/AnnoSys: Denotes the base URL of the stable and released AnnoSys system.
${ServicesURL} = https://annosys.bgbm.fu-berlin.de/AnnoSys: Denotes the base URL of the the stable and released AnnoSys web services.

Please report errors to the AnnoSys Project Team.

Integrating AnnoSys with Data Portals

AnnoSys provides the following types of interfaces for integration with Data Portals or other applications

Invoking the AnnoSys user interface
Retrieving record or annotation related information from AnnoSys web services

User interface invocation

The user interface can be invoked either to enable portal users to annotate the data record currently reviewed in the data portal, to examine an annotation related to the data record or to redirect users to the AnnoSys application main page including an annotation search interface.

The search interface can be invoked by redirecting web browsers to ${AnnoSysURL}.

To enable users to annotate a data record, the relating data must be transferred to the AnnoSys application first. Then, the user will be redirected to the AnnoSys Annotation Editor. This may be done either by providing AnnoSys with a URL, where the document can be downloaded by AnnoSys directly, or by providing a set of parameters instructing AnnoSys to download the corresponding data record from a BioCASE provider.

Note: The values for any parameters described in the next sections MUST be URL encoded individually(!) in order to be correctly transmitted via the URL to AnnoSys !

Download via direct URL

The URL referring to the record data document to be passed to AnnoSys via the parameter recordURL, i.e.

recordURL: The parameter should contain the URL of the document to be downloaded.

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/AnnoSys?recordURL=http://api.gbif.org/v1/occurrence/annosys/736268484

The URL may refer to the following types of documents

ABCD2.06 based XML data record(s)
BioCASE response documents containing ABCD2.06 based XML data record(s)
ABCD Archives containing either ABCD2.06 based XML data record(s) or BioCASE response documents
A Simple Darwin Core based XML data record
Darwin Core Archives containing data record(s) according to the Darwin Core Standard

In case of any of the document holds more than a single data record, the AnnoSys user interface provides a record selection dialog where annotators may select records for further being processed as multiple individual annotations from a list of successfully transmitted data records.

Download via BioCASE Provider

The BioCASE provider and the data record to be retrieved by AnnoSys must be passed via the following parameter set

providerURL: The base URL of the BioCASE provider (e.g. http://ww3.bgbm.org/biocase/pywrapper.cgi?dsa=Herbar&).
protocolURI: The namespace URI of the protocol used by the BioCASE provider (e.g. http://www.biocase.org/schemas/protocol/1.3).
formatURI: The namespace URI of the document format to be retrieved (e.g. http://www.tdwg.org/schemas/abcd/2.06).
institution: The institution (lsid:authority) part of the tripleId describing the record (e.g. BGBM).
source: The source (lsid:namespace) part of the tripleId describing the record (e.g. Herbarium Berolinense).
unitID: The unitID (lsid:objectId) part of the tripleId describing the record (e.g. B 20 0145120).

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/AnnoSys?providerURL=http%3A%2F%2Fww3.bgbm.org%2Fbiocase%2Fpywrapper.cgi%3Fdsa%3DHerbar%26&protocolURI=http%3A%2F%2Fwww.biocase.org%2Fschemas%2Fprotocol%2F1.3&formatURI=http%3A%2F%2Fwww.tdwg.org%2Fschemas%2Fabcd%2F2.06&institution=B&source=Herbarium%20Berolinense&unitID=B%2040%200025800

Opening Annotation View or Annotation Editor from AnnoSys repository objects

The repository URI corresponds to the UUID identifier used to retrieve any data stored in the AnnoSys repository like annotations or annotated records through AnnoSys' Linked Open Data Services described in section Web Services.

The URI referring repository data object can be passed to AnnoSys via the parameter repositoryURI, i.e.

repositoryURI: The parameter must contain a valid URI dereferencing an annotation or annotated record from the AnnoSys repository.

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/ca69ae44-4f88-11e8-a174-63cec1a86939

Examples of AnnoSys dataportals integrations

The following example links are all referring to the same object: B 40 0025800 (Padina Pavonia):

Herbarium Berolinense – Virtual Herbarium
BiNHum Sammlungsportal des Humboldt-Rings
World Flora Online Specimen Explorer for Phytotaxonomists
Global Biodiversity Information Facility (Please use the speech bubble on the menu right left to the "Login"-button, then select one of the "Content issues")
BIOCASE portal for BGBM collection

Links to AnnoSys:

This example refers to Dracaena ovata:

Meise Botanical Collections

Links to AnnoSys:

Web Services

AnnoSys provides two kinds of web services.

Linked Open Data (LOD) services
RESTful services

The Linked Open Data services provide access to resources referring to data stored in the AnnoSys repository. Therewith, annotations can be retrieved as RDF data, and the relating record documents as XML documents.

The RESTful services provide access to other information related to annotations or records, like if there are annotations stored in the repository for a given record.

Actually, AnnoSys provides the following service entries:

${ServicesURL}/repository

For legacy reasons e.g. to data portals connected AnnoSys I, AnnoSys also provides the former (legacy) service entries:

${ServicesURL}/services/annotations
${ServicesURL}/services/records

Additional services may be implemented on request.

The next sections will provide detailed information regarding the provided services.

Note: The values for any parameters described in the next sections MUST be URL encoded individually(!) in order to be correctly interpreted by AnnoSys Web Services !

Repository

The general context path for annotations is ${ServicesURL}/repository.

All repository requests return an either an RDF graph containing the repository object as described in our repository object model or a JSON annotation object as described in section JSON Annotation Object.

The following sections will describe possible requests and answers.

Request: GET ${ServicesURL}/repository/records

Returns a JSON object containing a list of URLs referring to to all available annotations in the AnnoSys repository.

size: number of records
records: list of list of record URI's

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/records
{
   "size": 4,
   "records": [
		"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/ebb228c9-3101-11e8-91bc-a56c89740491",
		"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/330e9167-2ede-11e8-b208-6595b3775167", 
		"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/330e91a0-2ede-11e8-b208-6595b3775167",
		"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/330e9191-2ede-11e8-b208-6595b3775167" 	
	]
}

Request: GET ${ServicesURL}/repository/annotations

Returns a JSON object containing a list of JSON Annotation Objects referring to to all available annotations in the AnnoSys repository.

size: number of annotations
annotations: list of JSON Annotation Objects

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/annotations
{
   "size": 2,
   "annotations": [
		{
			"repositoryURI": "https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/e8f9d4f9-2edc-11e8-b914-6f11f81e2994",
			"recordURIs": [
				"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/e8fc1eea-2edc-11e8-b914-6f11f81e2994"
			],
			"annotator": "Okka Tschöpe",
			"time": 1497871966380,
			"motivation": "Determination"
		},
		{
			"repositoryURI": "https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/ec409be1-2edc-11e8-b914-6f11f81e2994",
			"recordURIs": [
				"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/ec42e5d2-2edc-11e8-b914-6f11f81e2994"
			],
			"annotator": "Wolf-Henning Kusber",
			"time": 1504034932827,
			"motivation": "Nomenclatural type"    
		}
	]
}

Request: GET ${ServicesURL}/repository/agents

Returns a JSON object containing a list of JSON Agent Objects referring to to all available agents in the AnnoSys repository.

size: number of annotations
annotations: list of JSON Agent Objects

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/agents
{
	"size": 98,
	"agents": [
		{
			"repositoryURI": "https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/551d17d0-2edd-11e8-b914-6f11f81e2994",
			"name": "Wolf-Henning Kusber",
			"type": "http://xmlns.com/foaf/0.1/Person",
			"organisations": []
	 	},
		{
			"repositoryURI": "https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/55204b3c-2edd-11e8-b914-6f11f81e2994",
			"name": "Botanic Garden and Botanical Museum Berlin",
			"type": "http://xmlns.com/foaf/0.1/Organization",
			"organisations": []
		}, 
		{
			"repositoryURI": "https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/551cc9a6-2edd-11e8-b914-6f11f81e2994",
			"name": "AnnoSys Release 2016.04.22",
			"type": "http://xmlns.com/foaf/0.1/Software",
			"organisations": []
		}
	]
}

Request GET ${ServicesURL}/repository/<uuid>

Returns the repository object with the given UUID as RDF graph, if it exists. Otherwise, HTTP-Status 404 is returned.

Parameters

format (optional): The RDF output format may be selected by the optional parameter format. Any format supported by Apache Jena may be chosen (defaults to JSONLD).

Note: If the request is issued from a web browser, then the user will be redirected to the corresponding Annotation View or Annotation Editor in the AnnoSys user interface respectively. In particular this will be done if the HTTP GET Request includes an Accept-header containing the keyword "html".

Examples: https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/e8f9d4f9-2edc-11e8-b914-6f11f81e2994
          https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/e8f9d4f9-2edc-11e8-b914-6f11f81e2994?format=TURTLE

Annotations (Legacy)

The general context path for annotations is ${ServicesURL}/services/annotations.

All annotation requests return an either an RDF graph containing the annotations as described in our annotation model or a JSON annotation object as described in section JSON Annotation Object.

The following sections will describe possible requests and answers.

Request: GET ${ServicesURL}/services/annotations

Returns a JSON object containing a list of JSON objects referring to to all available annotations in the AnnoSys repository.

size: number of annotations
annotations: list of JSON Annotation Objects

Example: https://annosys.bgbm.fu-berlin.de/AnnoSysTest/services/annotations
{
   "size": 2,
   "annotations": [
		{
			"repositoryURI": "https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/e8f9d4f9-2edc-11e8-b914-6f11f81e2994",
			"recordURIs": [
				"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/e8fc1eea-2edc-11e8-b914-6f11f81e2994"
			],
			"annotator": "Okka Tschöpe",
			"time": 1497871966380,
			"motivation": "Determination"
		},
		{
			"repositoryURI": "https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/ec409be1-2edc-11e8-b914-6f11f81e2994",
			"recordURIs": [
				"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/ec42e5d2-2edc-11e8-b914-6f11f81e2994"
			],
			"annotator": "Wolf-Henning Kusber",
			"time": 1504034932827,
			"motivation": "Nomenclatural type"    
		}
	]
}

Request GET ${ServicesURL}/services/annotations/<uuid>

Returns the annotation with the given annotationId as RDF graph, if it exists. Otherwise, HTTP-Status 404 is returned. The RDF document format may be selected by the optional parameter format. Any format supported by Apache Jena may be chosen (defaults to JSONLD).

Note: If the request is issued from a web browser, then the user will be redirected to the corresponding Annotation View in the AnnoSys user interface. In particular this will be done if the HTTP GET Request includes an Accept-header containing the keyword html.

Examples: https://annosys.bgbm.fu-berlin.de/AnnoSys/services/annotations/e8f9d4f9-2edc-11e8-b914-6f11f81e2994
          https://annosys.bgbm.fu-berlin.de/AnnoSys/services/annotations/e8f9d4f9-2edc-11e8-b914-6f11f81e2994?format=TURTLE

Records (Legacy)

The general context path for records is ${ServicesURL}/services/records.

Records are identified within the AnnoSys repository by their UUID.

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/services/records/d5a2a93e-2edc-11e8-b914-6f11f81e2994

Request: GET ${ServicesURL}/services/records

Returns a JSON object containing a list of URLs referring to to all available annotations in the AnnoSys repository.

size: number of records
records: list of list of record URI's

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/services/records
{
   "size": 4,
   "records": [
		"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/ebb228c9-3101-11e8-91bc-a56c89740491",
		"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/330e9167-2ede-11e8-b208-6595b3775167", 
		"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/330e91a0-2ede-11e8-b208-6595b3775167",
		"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/330e9191-2ede-11e8-b208-6595b3775167" 	
	]
}

Request: GET ${ServicesURL}/services/records/<lsid:authority>/<lsid:namespace>/<lsid:objectId>/annotations

Returns a JSON object containing information about all annotations referring to the record in the AnnoSys repository according to the given record tripleId. In particular, this includes annotations created for all record versions stored in the AnnoSys record repository.

Otherwise, HTTP-Status 404 is returned if no such record exists.

record: URI of the most recent record for the given tripleId.
hasAnnotation: true or false.
size: number of annotations found related to the most recent record.
annotations: list of JSON Annotation Objects.

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/services/records/B/Herbarium+Berolinense/B+40+0025800/annotations
{
	"record": "https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/d5a2a93e-2edc-11e8-b914-6f11f81e2994",
	"hasAnnotation": true,
	"size": 2,
	"annotations": [
		{
			"repositoryURI": "https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/ea3cb55d-2edc-11e8-b914-6f11f81e2994",
			"recordURIs": [
				"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/d5a2a93e-2edc-11e8-b914-6f11f81e2994"
			],
			"annotator": "Wolf-Henning Kusber",
			"time": 1406024546055,
		 	"motivation": "Determination"
		},
		{
			"repositoryURI": "https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/d59f9bfd-2edc-11e8-b914-6f11f81e2994",
			"recordURIs": [
				"https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/d5a2a93e-2edc-11e8-b914-6f11f81e2994"
			],
			"annotator": "Wolf-Henning Kusber",
			"time": 1406023974657,
			"motivation": "Gathering"
		}
	]
}

JSON Annotation Object

An JSON Annotation Object contains the following meta information about an annotation which is intended for being displayed at a data portal user interface:

repositoryURI: URI of the annotation within the AnnoSys repository
recordURIs: list of record URI's belonging to that annotation
annotator: name of the annotating agent
time: annotation's publication time in milliseconds since 01 January 1970
motivation: the annotation's motivation or annotation type

JSON Agent Object

An JSON Agent Object contains the following meta information about an agent either stored as annotation creator, generator or organisation one of the former's may belong to:

repositoryURI: URI of the agent within the AnnoSys repository.
name: agent's name.
type: agent's type ( http://xmlns.com/foaf/0.1/Person, http://xmlns.com/foaf/0.1/Organization or http://xmlns.com/foaf/0.1/Software)
organisations: list of JSON Agent Objects containing the meta information of the organisations the current agent may be member of.

SPARQL Endpoint

AnnoSys also provides a SPARQL endpoint enabling external services or applications to run self-defined queries against the AnnoSys annotation repository. The SPARQL endpoint is driven by Virtuoso Open Source.

The URL of the AnnoSys SPARQL endpoint is: https://annosys.bgbm.fu-berlin.de/sparql.

TechnicalDocumentation-AnnoSys2

Contents