Revision as of 14:19, 14 January 2014

Preliminaries

Within this document, 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 AnnoSys system.

${ServicesURL} = https://annosys.bgbm.fu-berlin.de/AnnoSys/services

Denotes the base URL of the AnnoSys web services.

Currently, only ABCD2.06 based XML data records are supported ! (namespacePrefix "abcd2.06b")

Annotations are stored and will be delivered on request in RDF according to our implementation of the W3C Open Annotation Data Model described here.

The AnnoSys - Quick User Guide provides a basic introduction using the AnnoSys user interface.

Note: The AnnoSys software and services are currently beta releases and may have errors !. 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 redirect users to the AnnoSys search interface or to enable users to annotate a data record currently reviewed in the data portal. The search interface can be invoked by redirecting web browsers to ${AnnoSysURL}.

To enable users to annotate a data record, the relating XML document must be transferred to the AnnoSys repository. After successfully transferring the document, the user will be redirected to the AnnoSys user login/registration dialog first and subsequently to the AnnoSys Annotation Editor. This can be done either by providing a URL, where the document can be downloaded by AnnoSys directly, or by providing a set of parameters describing how AnnoSys can download the 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 can 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://ww2.biocase.org/svn/annotation/original/03666bc0-f0f4-11d8-b22f-b8a03c50a862/abcd2.06/BGBM/Bridel%20Herbar/Bridel-1-12.xml

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=BGBM&source=Herbarium%20Berolinense&unitID=B%2020%200145120

Opening Annotation View or Annotation Editor from http-reference URI

The http-reference URI corresponds to the resource id used to retrieve annotation data as RDF or XML record documents from the repository 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.

recordURI

The parameter must contain a valied URI dereferencing an annotation or XML record in the AnnoSys repository.

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/AnnoSys?repositoryURI=https%3A%2F%2Fannosys.bgbm.fu-berlin.de%2FAnnoSys%2Fservices%2Fannotations%2FBGBM%2FAnnoSys%2F1378396890596

Information Retrieval

Information related to a given record triple id can be retrieved via AnnoSys RESTful web services. Currently, the following record related information can be retrieved:

• Annotations

Returns, if the AnnoSys repository knows the record of the given triple id and, if there are annotations, also the number of annotations the given record. For more detailed information, see Request: GET ${ServicesURL}/records/<lsid:authority>/<lsid:namespace>/<lsid:objectId>/annotations.

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.

Additional services may be implemented on request.

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

Annotations

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

The annotation id is constructed analogously to tripleIds(or LSIDs) by our institution(lsid:authority), our source(lsid:namespace) and an annotation id(lsid:objectId) (e.g. /BGBM/AnnoSys/123456789).

All annotation requests return an rdf graph containing the annotations as described in our annotation model. (?Link).

The following sections will describe possible requests and answers.

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 !

Request: GET ${ServicesURL}/annotations

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

size

number of annotations

annotations

list of annotation URLs

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/services/annotations
{
  "size": 2,
  "annotations": ["https://annosys.bgbm.fu-berlin.de/AnnoSys/services/annotations/BGBM/AnnoSys/1378396890596","https://annosys.bgbm.fu-berlin.de/AnnoSys/services/annotations/BGBM/AnnoSys/1378396868015"]
}

Request GET ${ServicesURL}/annotations/BGBM/AnnoSys/<annotationId>

Returns the annotation with the given annotationId as RDF, if it exists. Otherwise, HTTP-Status 404 is returned if no such annotation exists.

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/services/annotations/BGBM/AnnoSys/1378396890596

Records

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

Records are identified within the AnnoSys repository by an extended LSID, including LSID data plus a prefix describing the document format. Thus, the path to be appended to the general records context path is build up on the tripleId, plus a timestamp stating lsid:version and an AnnoSys predefined namespacePrefix identifying the record's document format. Currently, only abcd2.06b is supported.

Example: /BGBM/Herbarium Berolinense/B -W 00400 -00 0/3534524354/abcd2.06b

Request: GET ${ServicesURL}/records/<lsid:authority>/<lsid:namespace>/<lsid:objectId>/<lsid:version>/<annosys:formatPrefix>

Returns the record document for the given extended LSID identifier. Otherwise, HTTP-Status 404 is returned if no such record exists.

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/services/records/BGBM/Herbarium+Berolinense/B+18+0014862/1379406965371/abcd2.06b

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

Returns a JSON object containing information about all annotations referring to the most recent record in the AnnoSys repository according to the given record tripleId. 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 URLs referring to found related to the most recent record.

Example: https://annosys.bgbm.fu-berlin.de/AnnoSys/services/records/BGBM/Herbarium+Berolinense/B+18+0014862/annotations
{ 
  "record" : "https://annosys.bgbm.fu-berlin.de/AnnoSys/services/records/BGBM/Herbarium+Berolinense/B+18+0014862/1379406965371/abcd2.06b"
  "hasAnnotation: true,
  "size": 2,
  "annotations": ["https://annosys.bgbm.fu-berlin.de/AnnoSys/services/annotations/BGBM/AnnoSys/1379917872836","https://annosys.bgbm.fu-berlin.de/AnnoSys/services/annotations/BGBM/AnnoSys/1379918822364"]
}

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

Same as before, but retrieves all annotations referring to the given record.

References