Difference between revisions of "TechnicalDocumentation-AnnoSys2"
L.suhrbier (talk | contribs) (→Examples of AnnoSys dataportals integrations) |
L.suhrbier (talk | contribs) (→Examples of AnnoSys dataportals integrations) |
||
| Line 74: | Line 74: | ||
Links to AnnoSys: | Links to AnnoSys: | ||
| − | * [https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/ccd8b1b6-4f88-11e8-a174-63cec1a86939 | + | * [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 | + | * [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 | + | * [https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/ccd5f295-4f88-11e8-a174-63cec1a86939 Annotation 2] |
| Line 83: | Line 83: | ||
Links to AnnoSys: | Links to AnnoSys: | ||
| − | * [https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/9012b562-719d-11e9-8432-9536df224110 | + | * [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 | + | * [https://annosys.bgbm.fu-berlin.de/AnnoSys/repository/901d8ad3-719d-11e9-8432-9536df224110 Annotation] |
== Web Services == | == Web Services == | ||
Latest revision as of 17:30, 24 September 2020
Contents
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:
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.
