ClientHelperAPI

Convenience methods for creating annotations

These methods create annotation rdf documents compliant with particular domain business expectations.

InsertIdentification

http://localhost:8080/clientHelper/insertIdentification - POST json (example below) containing annotation data

Annotation data as json:

{
  "target" : {
    "source" : "http://filteredpush.org/ontologies/oa/oad#AnySuchResource",
    "collectionCode" : "NEBC",
    "catalogNumber" : "barcode-00339174",
    "institutionCode" : "Harvard University"
  },
  "body" : {
    "scientificName" : "Dichanthelium acuminatum subsp. columbianum",
    "scientificNameAuthorship" : "(Scribner) Freckmann & Lelong",
    "name" : "Walter T. Kittredge",
    "dateIdentified" : "1991"
  },
  "evidence" : {
    "chars" : "Example"
  },
  "annotator_name" : "Paul J. Morris",
  "annotator_email" : "paul.morris@example.com",
  "uri" : "http://filteredpush.org/ontologies/annotation/e281f1fb-b0a8-4217-9f39-84f62a5247b8"
}

InsertGeoreference

http://localhost:8080/clientHelper/georeference - POST json containing georeference annotation data. See example below.

Annotation data as json:

{
 "target" : {    
   "source" : "http://purl.oclc.org/net/edu.harvard.huh/guid/uuid/ff8f6dc8-8fb1-4cd1-908d-cd91eef3d4e5",
   "collectionCode" : "IP",
   "catalogNumber" : "barcode-00339174",
   "institutionCode" : "MCZ"
 },
 "body" : {
   "geodeticDatum"	: "WGS84" ,
   "decimalLatitude" 	:  "45.2117337" , 
   "decimalLongitude" 	: "-83.3918094" ,
   "coordinatePrecision" 		: "9" ,
   "coordinateUncertaintyInMeters" 	: "281" ,
   "footprintSRS" 		: "4092" ,
   "georeferenceProtocol" 	: "Biogeomancer, Point Radius" , 
   "georeferenceRemarks" 	:  "Locality on shoreline, reached on foot off of dirt road.  Geoferenced from PLSS coordinate and memory of locality, P.J.Morris, 2012." ,
   "hasGeoreferenceSource" 	: "doi:10.2307/1306086" , 
   "georeferenceVerificationStatus" : "verified by collector",
   "georeferencedBy" : "Paul J. Morris" 
 },
 "evidence" : {
   "verbatimLocality" : "Coast of lake Huron at Rockport Beach (SW 1/4, W 1/2 sec. 31, T33N, R9E Michigan Geological Society locality 39)"
 },
 "annotated" : "2014-05-20T14:29:09.25Z",
 "annotator_name" : "Robert A. Morris",
 "annotator_email" : "Robert.morris@example.com",
 "uri" : "http://filteredpush.org/ontologies/annotation/e281f1fb-b0a8-4217-9f39-84f62a5247b9"
 }

ResponseAnnotation

http://localhost:8080/clientHelper/responseAnnotation - POST json containing response annotation data. See example below:

{
  "target" : {
    "annotationUri" : "http://filteredpush.org/ontologies/annotation/1719d458-8cb5-4cff-871a-d5f0a2f94d66",
    "resolution" : {
      "name" : "fixed"
    }
  },
  "body" : {
    "id" : "c68b4bed-29f1-4c88-95ac-2aebae5f43a3",
    "polarity" : {
      "name" : "negative"
    },
    "describesObject" : {
      "annotationUri" : "http://filteredpush.org/ontologies/annotation/1719d458-8cb5-4cff-871a-d5f0a2f94d66",
      "resolution" : {
        "name" : "fixed"
      }
    },
    "opinionText" : "This is wrong."
  },
  "annotator_name" : "Paul J. Morris",
  "annotator_email" : "paul.morris@example.com",
  "annotator_mboxSha1sum" : "c5de5abaddfd5b87f270d31faaadfa45e83e812d",
  "annotated" : "2014-04-28T12:15:47-0700",
  "generated" : "2014-04-28T12:15:47-0700",
  "uri" : "http://filteredpush.org/ontologies/annotation/1b18746e-529c-4f51-8679-5cf12857242c"

}

FP Helper Methods

These methods assist a client in interacting with FP Network nodes.

RegisterInterest

http://localhost:8080/clientHelper/registerInterest - GET query parameters are substituted as a key value pair filter as part of the interest query. Multiple parameters are supported. The response contains an interest id which can later be used in the call to checkInterest to obtain annotations that satisfy the interest. Available parameters are:

• createdBy
• catalogNumber
• collectionCode
• institutionCode
• identifiedBy
• scientificName
• scientificNameAuthorship
• family
• genus
• georeferencedBy

An example of a request to register an interest: http://localhost:8080/clientHelper/registerInterest?collectionCode=NEBC

QueryAnnotations

http://localhost:8080/clientHelper/findAnnotations - GET works much the same as register interest however the query is executed immediately and is not persisted (no interest to follow up on at a later date). Will return a list of annotation digests (summary) as json. Available parameters are as follows:

• createdBy
• catalogNumber
• collectionCode
• institutionCode
• identifiedBy
• scientificName
• scientificNameAuthorship
• family
• genus
• georeferencedBy

An example of a request to query annotations: http://localhost:8080/clientHelper/findAnnotations?collectionCode=NEBC

Example of the response (annotation digests):

[
   {
      "createdBy":"Greg Riccardi",
      "catalogNumber":"AD98001",
      "date":"2014-04-24T19:28:24Z",
      "type":"http://filteredpush.org/ontologies/oa/dwcFP#Identification",
      "uri":"http://filteredpush.org/ontologies/annotation/c570528f-3190-446c-9840-5a4cc37c7e4f",
      "collectionCode":"Martin Wiemers' collection, University of Vienna"
   } ...
]

NOTE: to obtain the full annotation using the uri from the digest call getAnnotation or getAnnotationConversations

GetAnnotationByUri

http://localhost:8080/clientHelper/getAnnotation - GET supply the uri of the annotation you wish to query as a parameter. Will return the annotation rdf/xml for that annotation.

Example invocation: http://localhost:8080/clientHelper/getAnnotation?uri=http://filteredpush.org/ontologies/annotation/c570528f-3190-446c-9840-5a4cc37c7e4f

GetAnnotationConversations

http://localhost:8080/clientHelper/findAnnotationConversations - GET executes a parameterized query that will obtain annotations and all responses as json.

Example invocation: http://localhost:8080/clientHelper/findAnnotationConversations?institutionCode=Harvard University

Example of result (contains original annotations and all responses:

[
   {
      "createdBy":"Paul J. Morris",
      "opinionText":"This is wrong.",
      "polarity":"http://filteredpush.org/ontologies/polarity/negative",
      "catalogNumber":"barcode-00339174",
      "date":"2014-01-31T22:20:43.938Z",
      "type":"http://purl.org/marl/ns/Opinion",
      "uri":"http://filteredpush.org/ontologies/annotation/5d825640-4312-4ed7-a126-cad1a19decd7",
      "collectionCode":"NEBC",
      "describesObject":"http://filteredpush.org/ontologies/annotation/61c2bfee-a098-45fa-adca-3aea52a6ab27"
   },
   {
      "createdBy":"Paul J. Morris",
      "opinionText":"This is wrong.",
      "polarity":"http://filteredpush.org/ontologies/polarity/negative",
      "catalogNumber":"barcode-00339174",
      "date":"2014-01-31T22:20:43.938Z",
      "type":"http://purl.org/marl/ns/Opinion",
      "uri":"http://filteredpush.org/ontologies/annotation/5d825640-4312-4ed7-a126-cad1a19decd7",
      "describesObject":"http://filteredpush.org/ontologies/annotation/61c2bfee-a098-45fa-adca-3aea52a6ab27"
   },
   {
      "scientificName":"Dichanthelium acuminatum subsp. columbianum",
      "createdBy":"Paul J. Morris",
      "catalogNumber":"barcode-00339174",
      "date":"2014-01-31T22:20:39.569Z",
      "type":"http://filteredpush.org/ontologies/oa/dwcFP#Identification",
      "dateIdentified":"1991",
      "uri":"http://filteredpush.org/ontologies/annotation/61c2bfee-a098-45fa-adca-3aea52a6ab27",
      "collectionCode":"NEBC"
   } ...
]

CheckInterest

http://localhost:8080/clientHelper/checkInterest - GET takes a single parameter interestId and returns the annotation digests (xml) of annotations that satisfy the interest.

FindAnalysisResults

http://localhost:8080/clientHelper/findAnalysisResults - GET takes parameters to the query on analysis results and returns the original record, analsysi result and provenance data as json:

FindResponseAnnotations

http://localhost:8080/clientHelper/findResponseAnnotations - GET given a uri for an annotation as a parameter will return a list of annotation digests (xml) for all responses to the original annotation