Difference between revisions of "TechnicalDocumentation-AnnoSys2"

From Annotationssystem für Biodiversitätsdaten
Jump to: navigation, search
(→‎Request GET ${ServicesURL}/export)
(→‎Examples of AnnoSys dataportals integrations)
 
(4 intermediate revisions by the same user not shown)
Line 72: Line 72:
 
* [http://www.gbif.org/occurrence/144881790 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")
 
* [http://www.gbif.org/occurrence/144881790 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")
 
* [http://search.biocase.org/bgbm/search/units/details/getDetails?institutionID=B&collectionID=Herbarium+Berolinense&unitID=B+40+0025800&resourceKey=12888&bioKey=144881790 BIOCASE portal for BGBM collection]
 
* [http://search.biocase.org/bgbm/search/units/details/getDetails?institutionID=B&collectionID=Herbarium+Berolinense&unitID=B+40+0025800&resourceKey=12888&bioKey=144881790 BIOCASE portal for BGBM collection]
 +
 +
Links to AnnoSys:
 +
* [https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/ccd8b1b6-4f88-11e8-a174-63cec1a86939 Record]
 +
* [https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/df8c23a7-4f88-11e8-a174-63cec1a86939 Annotation 1]
 +
* [https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/ccd5f295-4f88-11e8-a174-63cec1a86939 Annotation 2]
 +
 +
 +
This example refers to Dracaena ovata:
 +
* [http://www.botanicalcollections.be/#/en/specimen/BR0000022401762 Meise Botanical Collections]
 +
 +
Links to AnnoSys:
 +
* [https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/9012b562-719d-11e9-8432-9536df224110 Record]
 +
* [https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/901d8ad3-719d-11e9-8432-9536df224110 Annotation]
  
 
== Web Services ==
 
== Web Services ==
Line 194: Line 207:
 
  Examples: https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/e8f9d4f9-2edc-11e8-b914-6f11f81e2994
 
  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
 
           https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/e8f9d4f9-2edc-11e8-b914-6f11f81e2994?format=TURTLE
−
 
−
==== Request GET ${ServicesURL}/backup ====
 
−
Backups the AnnoSys repository's RDF graph to the given (server local) file path.
 
−
 
−
In order to work, the ''Service.enableBackup'' property must be set to ''true''. Otherwise, HTTP-Status 404 is returned.
 
−
 
−
Any exception thrown during the import process will result in anHTTP-Status 500 to be returned.
 
−
 
−
;Parameters:
 
−
:;location
 
−
::The server local file path where the backup model shall be written.
 
−
:;format (optional)
 
−
::The RDF output format may be selected by the optional parameter ''format''. Any format [https://jena.apache.org/documentation/javadoc/arq/org/apache/jena/riot/RDFFormat.html supported by Apache Jena] may be chosen (defaults to ''JSONLD'').
 
−
 
−
Examples: [https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/backup?location=%2Ftmp%2Fbackup&format=TURTLE https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/backup?location=/tmp/backup&format=TURTLE]
 
−
 
−
==== Request GET ${ServicesURL}/restore ====
 
−
Restores the AnnoSys repository's RDF graph to the given (server local) file path.
 
−
 
−
In order to work, the ''Service.enableImport'' property must be set to ''true''. Otherwise, HTTP-Status 404 is returned.
 
−
 
−
Any exception thrown during the import process will result in anHTTP-Status 500 to be returned.
 
−
 
−
;Parameters:
 
−
:;location
 
−
::The server local backup file path where the repository shall be restored from.
 
−
 
−
Examples: https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/restore?location=\tmp\backup
 
  
 
=== Annotations (Legacy) ===
 
=== Annotations (Legacy) ===

Latest revision as of 17:30, 24 September 2020

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

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):

Links to AnnoSys:


This example refers to Dracaena ovata:

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:

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

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.

References

Retrieved from "https://wiki.bgbm.org/annosys/index.php?title=TechnicalDocumentation-AnnoSys2&oldid=237"