Brief description

Version

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

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

Assumptions

None.

References

• Entity Diagrams
• Scholarly Services - Linguistic+Analysis [NOTE: this link expected to BREAK on March 2013 migration FIX IT]
• 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

Client Responsibilities in Requests to Secured BSP Web Services

(1) A client must be configured as a Trusted Application if requests are to be treated other than as Anonymous

A client application – whether a web app or a simple testing client such as Firefox Poster or curl – may make requests anonymously or as a "Trusted Application." Only a Trusted Application may assert the identity of a user on behalf of whom the request is made, and scoped roles to be assigned to that user; Bamboo Services trust such clients to assert the identity and assigned-roles only of users who have authenticated in the current session of application activity. (A special-case type of client application, termed Innovation Licensed applications, are trusted to assert the identity of and roles assigned to a fixed set of special-case users without those users having to authenticate in the current session.)

Configuration of client applications are described in detail in this wiki page: Configure Apache Web Server for Client Auth. It is assumed in #2, below, that this configuration has been performed.

(2) A Trusted client is expected to pass HTTP Request Headers to identify itself and an authenticated user

A client application that is Trusted in the security context of the Bamboo Trust Federation (cf. Identity and Access Management - Authentication and Authorization) must augment each request to a service hosted by a secured instance of the Bamboo Services Platform (BSP) with a set of HTTP headers, as follows:

• X-Bamboo-AppID: A UUID that identifies the client research environment, application, tool, or service; this UUID is issued as part of the process of registering a trusted client in the Bamboo Trust Federation as described in overview on the page Identity and Access Management - Authentication and Authorization; and in detail with respect to physical establishment of trust on the page Configure Apache Web Server for Client Auth. The value of this header is linked to the X.509 certificate by which the application establishes an SSL connection to the BSP host in the registration process, and a match between this Application ID and the linked X.509 certificate is checked by the BSP on receipt of every request.

• X-Bamboo-BPID: A UUID that identifies the logged-in user on whose behalf the request is being sent; this value, a Bamboo Person Identifier, or BPId, is obtained via a call to the Person Service that occurs in time between user login and any other service request. See the Read a BambooPersonId method of the Person Service API for details. [^†]
• X-Bamboo-Roles: A pipe-delimited (|) set of scoped roles asserted by the trusted client to belong to the logged-in user, of the form role@domain, which are to be evaluated as factors in the determination of whether the request satisfies policies (access restrictions) that apply to the requested resource. If a user is authenticated, the client is expected to include the role undefined@domain where domain identifies the organization that authenticated the user (example: undefined@google.com is a client app's assertion that the user authenticated to Google). This header is otherwise optional (depending on policies governing the requested resource that may require one or more scoped roles for access to be permitted). Example of multiple roles asserted in this header: roleA@domainOne.xxx|roleB@domainTwo [^‡]

[^†] The value of X-Bamboo-BPID is set to the identifier for the application itself (X-Bamboo-AppID) when a client application calls the Person Service to create a new Bamboo Person Identifier; or to retrieve the BPId for a user based on the identifier of the IdP with which she has logged in and an SHA-256 hash of that IdP's user identifier for the logged-in person.

[^‡] Policies and policy evaluation are described on the page Authorization and Policy. Also see Conventions for representing Identity Providers in the Bamboo Trust Federation.

Schema

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

GET /morphologyservice/engine

Response

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

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:

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:

GET /morphologyservice/engine/{EngineId}

Example:

GET /morphologyservice/engine/morpheus HTTP/1.1

Response

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

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:

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:

GET /morphologyservice/repository

Response

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

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:

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:

GET /morphologyservice/repository/{RepoId}

Example:

GET /morphologyservice/repository/xmlRepository HTTP/1.1

Response

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

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:

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:

GET /bsp/morphologyservice/analysis/word HTTP/1.1
POST /bsp/morphologyservice/analysis/word HTTP/1.1

• This request is always synchronous (i.e. response returns and is not cached).

Example:

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:

A response with HTTP 201 (CREATED) status 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:

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:

GET /bsp/morphologyservice/analysis/document HTTP/1.1
POST /bsp/morphologyservice/analysis/document HTTP/1.1

Example:

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:

A response with HTTP 201 (CREATED) status 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. |

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:

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:

GET /bsp/morphologyservice/analysis/text HTTP/1.1
POST /bsp/morphologyservice/analysis/text HTTP/1.1

Example:

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:

A response with HTTP 201 (CREATED) status 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:

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