Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Table of Contents
maxLevel3
minLevel1

Brief description

Version

This page describes the Morphological Analysis Service API, v. 1.1.1

Note

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 Morphological Analysis Service responds to requests for morphological analysis of texts, submits them to the appropriate morphology engine for processing and returns the results in XML adhering to a standard morphology schema.  The Service supports retrieval of texts for analysis from remote repositories as well as user-supplied chunks of text.  URL based and CTS repositories are supported.  Where retrieval from a CTS enabled repository is requested CTS URNs are supported as document identifiers. Where retrieval from a URL based repository is requested, URIs are supported as document identifiers.

For a full description, visit the Morphological Analysis Service Description and Assumptions - v1.1.1 page of this wiki (a child to this page).

Assumptions

None.

References

Excerpt Include
Bamboo Repository Location
Bamboo Repository Location
nopaneltrueBamboo Repository Location

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

Known Issues

  • BSPSVC-102 Does not yet support the ignore accents feature of the Morpheus engine
  • BSPSVC-87 Cannot configure which TEI tags to ignore when tokenizing text for analysis

ROA Layer API

RESTful service methods performing Create and List functions over Analyses, Morphology Engines and Text Repositories.

 

Base URLs

Excerpt Include
Web Service API Base URLs - FINAL DOCUMENTATION
nopaneltrue
Web Service API Base URLs - FINAL DOCUMENTATION
nopaneltrue

 

Client Responsibilities in Requests to Secured BSP Web Services

Tip

As of March 2013, policy for the Morphological Analysis Service permits anonymous access.


Excerpt Include
Client Responsibilities in Requests to Secured BSP Web Services
nopaneltrue
Client Responsibilities in Requests to Secured BSP Web Services
nopaneltrue

Schema

Excerpt Include
Bamboo Repository Location
Bamboo Repository Location
nopaneltrueBamboo Repository Location

  • EngineListRepresentation schema: ${REPOSITORY_ROOT}/platform-services/morphology-service/trunk/morphology-service/resource/src/main/resources/EngineListRepresentation.xsd
  • TextRepositoryListRepresentation schema: ${REPOSITORY_ROOT}/platform-services/morphology-service/trunk/morphology-service/resource/src/main/resources/TextRepositoryListRepresentation.xsd
  • alpheios lexicon schema

Morphology Engine

A morphological engine available for use by the service when producing morphological analyses.

List Engine instances

Lists the set of morphology engines configured for this instance of the service.

Calling Method and Arguments

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

...

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 EngineListRepresentation 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 Engine

Lists a specific morphology engine 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 /morphologyservice/engine/morpheus 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 EngineListRepresentation 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 for analysis. The 1.1.0 version of the services supports both CTS repositories and repositories which can respond to URI based requests.

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

...

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 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 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 /morphologyservice/repository/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

Analysis (Word)

Produce a morphological analyses of a supplied word or list of words.

Create a morphological analysis of a word or list of words

Calling Method and Arguments

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

...

Code Block
POST /bsp/morphologyservice/analysis/word 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: 63
word=χρόνῳ&lang=grc&engine=morpheus

Response

On success, a response with a "201 Created" HTTP status code will be returned:

...

Example: morph_response_word.xml

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:

...

Parameter

Meaning

HTTP Body

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

Analysis (Document)

Retrieve a requested document from a repository, tokenize it, and produce morphological analyses of the words contained within it.

Create morphological analyses of words in a document.

Calling Method and Arguments

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

...

Code Block
POST /bsp/morphologyservice/analysis/document 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: 158
lang=grc&engine=morpheus&document_id=http://www.perseus.tufts.edu/hopper/xmlchunk?doc=Perseus:text:1999.01.0025:card=1553&repos_type=xml

Response

On success, a response with a "201 Created" HTTP status code will be returned:

...

Example response where wait=0: morph_response_doc_wait.xml
Example of annotation after waiting (truncated to only first two words of document): morph_response_doc.xml

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:

...

Parameter

Meaning

HTTP Body

XML document with MorphologyServiceError as root element containing a descriptive message. For asynchronous requests that fail, the error message will be stored in cached result document.

Analysis (Text)

Tokenize the supplied text and produce morphological analyses of the words contained within it.

Create morphological analyses of the words in the supplied text.

Calling Method and Arguments

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

...

Code Block
POST /bsp/morphologyservice/analysis/text HTTP/1.1
Accept: application/json, text/javascript, */*
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: 71
lang=lat&engine=morpheus&mime_type=text/plain&text=veni vidi vici

Response

On success, a response with a "201 Created" HTTP status code will be returned:

...

For asynchronous requests (param wait=false) a response will with HTTP 202 (ACCEPTED) status will be returned. The response data will contain single annotation which represents a summary annotation for the document. 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:

...

Parameter

Meaning

HTTP Body

XML document with MorphologyServiceError as root element containing a descriptive message. For asynchronous requests that fail, the error message will be stored in cached result document.

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/morphology-service/trunk/morphology-service/resource/src/test/test.html

...