This wiki space contains archival documentation of Project Bamboo, April 2008 - March 2013.

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

Brief description

The Syntactic Annotation service provides retrieval, conversion and abstract query services  for annotated corpora.

Version

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

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

Overview and Definitions

The Syntactic Annotation Service 1.1.1 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 [INSERT LINK HERE] page of this wiki (a child to this page).

Assumptions

None.

References

  • Entity Diagrams
  • Codebase ${REPOSITORY_ROOT}/platform-services/annotation-service/trunk/annotation-service/

Known Issues

  • BSPSVC-83 Cannot configure which TEI tags to ignore when tokenizing text to create annotation templates. [NOTE: LINK WILL BREAK ON MIGRATION OF JIRA; FIX LINK]

ROA Layer API

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

Base URLs

Sample on this page is hard-coded text; over time, template will be altered to include URLs from a master page describing Prod and QA URLs, and perhaps others as the project wishes to make (for example) the Continuous Integration instance visible.

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:

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:

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:

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:

GET /annotationservice/repository/{RepoId}

Parameter

Supported Values

Accept Header

application/xml,text/xml,application/json

Example:

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:

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:

GET /annotationservice/textrepository/{RepoId}

Parameter

Supported Values

Accept Header

application/xml,text/xml,application/json

Example:

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:

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:

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:

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

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:

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:

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:

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:

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

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 at ${REPOSITORY_ROOT}/platform-services/annotation-service/trunk/annotation-service/resource/src/test/tests.html

 

  • No labels