Navigation:
Documentation
Archive



Page Tree:

Child pages
  • Syntactic Annotation Service Contract Description v0.8 - BDOC

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

Contract:

 

 

Wiki Markup
{multi-excerpt:name=serviceName}Syntactic Annotation{multi-excerpt}

 

 

 

Table of Contents
maxLevel3
minLevel1

Brief description

Version

This page describes the Syntactic Annotation Service API, v. 1.1.0.

Note

To discover the version and other metadata about deployed service code that fulfills this API, please utilize the Service Catalog Service - BDOC.

Overview and Definitions

The Syntactic Annotation Service 1.1.0 Release provides a standard API via RESTful HTTP and OSGI Service interfaces for requesting (a) syntactic annotations from supported annotation repositories and (b) templates for creation of syntactic annotations of passages and texts. It is currently configured with access to the Alpheios repository of the Perseus Greek and Latin treebank annotations. It can also retrieve text for annotation template creation from any CTS-API compliant repository, and can be easily configured to access other annotation and text repositories which provide HTTP based RESTful interfaces. The Syntactic Annotation service also supports plugins of PepperModules for converting between annotation formats. The Release 1.1.0 interface supports the Perseus import format and Perseus and PAULA export formats.

For a full description, visit the Syntactic Annotation Service Description and Assumptions page of Project Bamboo's development wiki.

Assumptions

None.

References

Known Issues

  • BSPSVC-83 Cannot configure which TEI tags to ignore when tokenizing text to create annotation templates.

ROA Layer API

RESTful service methods performing Create and List functions over Annotations, Annotation Repositories, Formats and Text Repositories.

Base URLs

Excerpt Include
Web Service API Base URLs - CURRENT - BDOC
Web Service API Base URLs - CURRENT - BDOC
nopaneltrue

Schema

Annotation Format

A format available for ingestion and serialization of annotation bodies. There are two sub-categories of formats: import and export. Import formats are those formats in which the service is able ingest annotations, and export formats are those formats to which the service is able to serialize annotations. Annotations may be converted from one format to another by supplying a format for export which differs from the annotations' import format.

List Export Formats

Lists the set of available export formats for annotations.

Calling Method and Arguments

Invoked as an HTTP GET method. Send an HTTP request of the form:

Code Block
GET /annotationservice/format/export HTTP/1.1

Parameter

Supported Values

Accept Header

application/xml,text/xml,application/json

Response

On success, a response with a "202 Accepted" HTTP status code will be returned:

Parameter

Meaning

HTTP Body

An instance of an AnnotationFormatListRepresentation schema XML document

Exceptions

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the Get request:

Error (Status Code)

Meaning

Returned When

400

Bad Request

Request is missing required parameters

500

Internal Server Error

A service error occurred

List Import Formats

Lists the set of supported import formats for annotations.

Calling Method and Arguments

Invoked as an HTTP GET method. Send an HTTP request of the form:

Code Block
GET /annotationservice/format/import HTTP/1.1

Parameter

Supported Values

Accept Header

application/xml,text/xml,application/json

Response

On success, a response with a "202 Accepted" HTTP status code will be returned:

Parameter

Meaning

HTTP Body

An instance of an AnnotationFormatListRepresentation schema XML document

Exceptions

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the Get request:

Error (Status Code)

Meaning

Returned When

400

Bad Request

Request is missing required parameters

500

Internal Server Error

A service error occurred

Format Options

Most requests to retrieve annotations, as documented below, support a format_option parameter in which you can supply instructions specific to the requested export format. In general, the valid values for this parameter depends on the 'specialParameters' parameters supported by the particular Pepper Importer/Exporter module for the requested template format. The following lists the the general parameters specific to the Syntactic Annotation Service which apply to all conversions between template formats:

  • pepperImporter.corpusName=<name of the corpus> (this option specifies the name to be used to represent the corpus being transformed)

Annotation Repository

A pre-configured annotation repository. The 1.1.0 release of the service supports remote url based repositories that follow a template pattern for retrieval of annotations according to an identifier or a specific type of annotation repository. These are the repositories from which the service can retrieve annotations.

List Annotation Repository instances

List the annotation repositories configured for this instance of the service.

Calling Method and Arguments

Invoked as an HTTP GET method. Send an HTTP request of the form:

Code Block
GET /annotationservice/repository

Parameter

Supported Values

Accept Header

application/xml,text/xml,application/json

Response

On success, a response with a "202 Accepted" HTTP status code will be returned:

Parameter

Meaning

HTTP Body

An instance of an AnnotationRepositoryListRepresentation schema XML document

Exceptions

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the Get request:

Error (Status Code)

Meaning

Returned When

400

Bad Request

Request is missing required parameters

404

Not Found

The requested document does not exist and/or the requested analysis returned no results

500

Internal Server Error

A service error occurred

List an Annotation Repository

List a specific annotation repository configured for this instance of the service.

Calling Method and Arguments

Invoked as an HTTP GET method. Send an HTTP request of the form:

Code Block
GET /annotationservice/repository/{RepoId}

Parameter

Supported Values

Accept Header

application/xml,text/xml,application/json

Example:

Code Block
GET /annotationservice/repository/alpheios HTTP/1.1

Response

On success, a response with a "202 Accepted" HTTP status code will be returned:

Parameter

Meaning

HTTP Body

An instance of an AnnotationRepositoryListRepresentation schema XML document

Exceptions

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the Get request:

Error (Status Code)

Meaning

Returned When

400

Bad Request

Request is missing required parameters

404

Not Found

The requested document does not exist and/or the requested analysis returned no results

500

Internal Server Error

A service error occurred

Text Repository

A repository from which texts/documents can be retrieved and transformed to create templates for annotation. The 1.1.0 version of the services supports both CTS repositories and repositories which can respond to URI based requests.

List Text Repository instances

List the text repositories configured for this instance of the service.

Calling Method and Arguments

Invoked as an HTTP GET method. Send an HTTP request of the form:

Code Block
GET /annotationservice/textrepository HTTP/1.1

Parameter

Supported Values

Accept Header

application/xml,text/xml,application/json

Response

On success, a response with a "202 Accepted" HTTP status code will be returned:

Parameter

Meaning

HTTP Body

An instance of an TextRepositoryListRepresentation schema XML document

Exceptions

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the Get request:

Error (Status Code)

Meaning

Returned When

400

Bad Request

Request is missing required parameters

404

Not Found

The requested document does not exist and/or the requested analysis returned no results

500

Internal Server Error

A service error occurred

List a specific Text Repository

List a specific text repository configured for this instance of the service.

Calling Method and Arguments

Invoked as an HTTP GET method. Send an HTTP request of the form:

Code Block
GET /annotationservice/textrepository/{RepoId}

Parameter

Supported Values

Accept Header

application/xml,text/xml,application/json

Example:

Code Block
GET /annotationservice/textrepository/xmlRepository HTTP/1.1

Response

On success, a response with a "202 Accepted" HTTP status code will be returned:

Parameter

Meaning

HTTP Body

An instance of an TextRepositoryListRepresentation XML document

Exceptions

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the Get request:

Error (Status Code)

Meaning

Returned When

400

Bad Request

Request is missing required parameters

404

Not Found

The requested document does not exist and/or the requested analysis returned no results

500

Internal Server Error

A service error occurred

Annotation

An annotation on a document, text or fragment.

Request a specific annotation or set of annotations

Calling Method and Arguments

Invoked as an HTTP GET or HTTP POST. Send an HTTP request of the form:

Code Block
GET /annotationservice/annotation HTTP/1.1
POST /annotationservice/annotation HTTP/1.1

parameter

accepted values

cardinality

notes

document_id

cts urn identifying the document, document fragment or token

1

 

template_format

code for the requested template format

1

 

format_option

format-specific option

0..1

 

repos_order

repository search order

0..1

 

filter

TBD filter for limiting results to a specific annotation if multiple exist

0..*

 

notify

email address or bamboo person id for notification upon completion

0..1

 

wait

true or false

0..1

if not supplied, default is true (request will be submitted synchronously)

Accept Header

application/xml,text/xml,application/json

 

 

Example:
The following request asks for all annotations on the document fragment identified as urn:cts:greekLit:tlg0085.tlg003.alpheios-text-grc1:1-100 (lines 1-100 of 'Prometheus Bound', from the 'alpheios' annotation repository:

Code Block
POST /bsp/annotationservice/annotation HTTP/1.1
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: 131
template_format=Perseus&lang=grc&document_id=urn%3Acts%3AgreekLit%3Atlg0085.tlg003.alpheios-text-grc1%3A1-100&repos_order=alpheios

Response

Synchronous requests (param wait=true)

A response with "200 (OK)" HTTP status code will be returned.

Parameter

Meaning

HTTP Body

OAC/RDF annotations as annotation body, adhering to the schema identified in the template_format request parameter.

Asynchronous requests (param wait=false)

A response with "202 (Accepted)" HTTP Status code will be returned

Parameter

Meaning

HTTP Body

A single annotation which represents a summary annotation for the request. The rdf:about value for the Annotation itself will be set to a urn representing a unique identifer for the request. The rdf:about value for the Annotation Body will be the url identifying the location the results will be stored at when complete.

Exceptions

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the request:

Error (Status Code)

Meaning

Returned When

400

Bad Request

Request is missing required parameters

404

Not Found

The requested annotations were not found or could not be retrieved.

500

Internal Server Error

A service error occurred

Parameter

Meaning

HTTP Body

XML document with AnnotationServiceError as root element containing a descriptive message.

Request an annotation or set of annotations matching certain criteria

Calling Method and Arguments

Invoked as an HTTP GET or HTTP POST. Send an HTTP request of the form:

Code Block
GET /annotationservice/annotation/match HTTP/1.1
POST /annotationservice/annotation/match HTTP/1.1

parameter

accepted values

cardinality

notes

document_id

cts urn identifying the document, document fragment or token

0..1

 

lang

language of interest

0..1

 

template_format

code for the requested template format

1

 

format_option

format-specific option

0..1

 

repos_order

repository search order

0..1

 

filterBy

filter field for match

1

(valid query options for each repository are available in the repository list output

filterOp

filter operation for match

1

(currently only supported value is 'equals' )

filterValue

filter field value match

1

 

notify

email address or bamboo person id for notification upon completion

0..1

 

wait

true or false

0..1

if not supplied, default is true (request will be submitted synchronously)

Accept Header

application/xml,text/xml,application/json

 

 

Example:

The following request asks for annotations on the document fragment identified as urn:cts:greekLit:tlg0085.tlg003.alpheios-text-grc1:1-100 (lines 1-100 of 'Prometheus Bound', in the 'alpheios' annotation repository, where the word's part of speech matches 'noun':

Code Block
POST /bsp/annotationservice/annotation/match HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: 177
template_format=Perseus&lang=grc&document_id=urn%3Acts%3AgreekLit%3Atlg0085.tlg003.alpheios-text-grc1%3A1-100&repos_order=alpheios&filterOp=equals&filterValue=noun&filterBy=pos

Response

Synchronous requests (param wait=true)

A response with "200 (OK)" HTTP status code will be returned.

Parameter

Meaning

HTTP Body

OAC/RDF annotations as annotation body, adhering to the schema identified in the template_format request parameter.

Asynchronous requests (param wait=false)

A response with "202 (Accepted)" HTTP Status code will be returned

Parameter

Meaning

HTTP Body

A single annotation which represents a summary annotation for the request. The rdf:about value for the Annotation itself will be set to a urn representing a unique identifer for the request. The rdf:about value for the Annotation Body will be the url identifying the location the results will be stored at when complete.

Exceptions

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the request:

Error (Status Code)

Meaning

Returned When

400

Bad Request

Request is missing required parameters

404

Not Found

The requested document was not found or could not be retrieved.

500

Internal Server Error

A service error occurred

Parameter

Meaning

HTTP Body

XML document with AnnotationServiceError as root element containing a descriptive message.

Annotation Template (Document)

An annotation template for a specified document.

Create an annotation template for a specific document.

Calling Method and Arguments

Invoked as an HTTP GET or HTTP POST. Send an HTTP request of the form:

Code Block
GET /annotationservice/annotation/template/document HTTP/1.1
POST /annotationservice/annotation/template/document HTTP/1.1

parameter

accepted values

cardinality

notes

document_id

document (or document fragment) id (cts urn, cmis object id)

1

 

repos_type

repository type (e.g. cts, xml)

0..1

 

repos_uri

base uri for the repository

0..1

 

lang

languages of interest in the document

1..*

 

template_format

code for the requested template format

1

 

format_option

format-specific option

0..1

 

notify

email address or bamboo person id for notification upon completion

0..1

 

wait

true or false

0..1

if not supplied, default is true (request will be submitted synchronously)

Accept Header

application/xml,text/xml,application/json

 

 

Example:

Code Block
POST /bsp/annotationservice/annotation/template/document HTTP/1.1
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: 164
template_format=Perseus&lang=lat&document_id=urn%3Acts%3AlatinLit%3Astoa0179.stoa001.stoa001%3A1.1.1&repos_type=cts&repos_uri=http%3A%2F%2Fhclatin.appspot.com%2FCTS

Response

Synchronous requests (param wait=true)

A response with "200 (OK)" HTTP status code will be returned.

Parameter

Meaning

HTTP Body

One or more OAC/RDF Annotation templates for requested text

Asynchronous requests (param wait=false)

A response with "202 (Accepted)" HTTP Status code will be returned

Parameter

Meaning

HTTP Body

A single annotation which represents a summary annotation for the request. The rdf:about value for the Annotation itself will be set to a urn representing a unique identifer for the request. The rdf:about value for the Annotation Body will be the url identifying the location the results will be stored at when complete.

Exceptions

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the request:

Error (Status Code)

Meaning

Returned When

400

Bad Request

Request is missing required parameters

404

Not Found

The requested document was not found or could not be retrieved.

500

Internal Server Error

A service error occurred

Parameter

Meaning

HTTP Body

XML document with AnnotationServiceError as root element containing a descriptive message.

Annotation Template (Text)

An annotation template for supplied text.

Create an annotation template for supplied text

Calling Method and Arguments

Invoked as an HTTP GET or HTTP POST. Send an HTTP request of the form:

Code Block
GET /annotationservice/annotation/template/text HTTP/1.1
POST /annotationservice/annotation/template/text HTTP/1.1

parameter

accepted values

cardinality

notes

text

the supplied text

0..1

 

text_uri

a uri for the supplied text

0..1

If both text and text_uri are supplied, the uri will be used as the identifier for the text only

template_format

code for the requested template format

1

 

mime_type

mime-type of the supplied text (text/html, text/xml, or text/plain)

1

 

format_option

format-specific option

0..1

 

lang

languages of interest in the supplied text

1..*

 

notify

email address or bamboo person id for notification upon completion

0..1

 

wait

true or false

0..1

if not supplied, default is true (request will be submitted synchronously)

Accept Header

application/xml,text/xml,application/json

 

 

Example:

Code Block
POST /bsp/annotationservice/annotation/template/text HTTP/1.1
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: 79
text=veni%20vidi%20vici&template_format=Perseus&lang=lat&mime_type=text%2Fplain

Response

Synchronous requests (param wait=true)

A response with "200 (OK)" HTTP status code will be returned.

Parameter

Meaning

HTTP Body

One or more OAC/RDF Annotation templates for requested text

Asynchronous requests (param wait=false)

A response with "202 (Accepted)" HTTP Status code will be returned

Parameter

Meaning

HTTP Body

A single annotation which represents a summary annotation for the request. The rdf:about value for the Annotation itself will be set to a urn representing a unique identifer for the request. The rdf:about value for the Annotation Body will be the url identifying the location the results will be stored at when complete.

Exceptions

If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the request:

Error (Status Code)

Meaning

Returned When

400

Bad Request

Request is missing required parameters

404

Not Found

The requested document was not found or could not be retrieved.

500

Internal Server Error

A service error occurred

Parameter

Meaning

HTTP Body

XML document with AnnotationServiceError as root element containing a descriptive message.

SOA Layer API

Note

Javadoc will be linked once it is generated and published.

See Javadoc.

Notifications

If the notify parameter has been supplied and set to an email address an email will be sent to that address upon completion of the request. If the notify parameter is set to a bamboo person id, notifications will be sent according to user preferences. The body of the notification messages will contain the unique identifier for the request (as returned in the rdf:about value for the annotation returned by the requested), the current status, and the location at which the results can be retrieved.

Tests

See Tests