HttpApiAnnotator

The HttpApiAnnotator is an annotator that can be used for implementing a custom annotator. It will execute a HTTP request containing the text that needs to be annotated and the annotations set by earlier annotators.

Your custom implementation should return new annotations based on your own analysis.

Configuration

The HttpApiAnnotator must be configured with an endpoint that implements the API.

Attribute

Description

Required

Default

endpoint

The URL of the HTTP API annotator implementation.

This attribute also supports environment variables.

Yes

N/A

inputAnnotationTypeIds

A list of annotation type identifiers that may be included in the request. Regardless of whether annotations are found or not, the request will always be sent.If this configuration is not set, all annotations set by earlier annotators will be included.

No

N/A

Include the documentId

You have the ability to include the documentId in the request to the HttpApiAnnotator by including the <experimental:appendDocumentIdToQueryString /> inside the `httpApiAnnotator`.When using this flag, the documentId will be appended to the endpoint as a query string parameter.

This configuration is experimental. You will need to add the following namespace declaration to your analysis configuration file:

Other

xmlns:experimental="http://schemas.fontoxml.com/fcq/1.0/experimental-analysis-configuration.xsd"

Configuring the editor

Make sure to register the returned annotation types as custom annotations inside the editor.

API

When using the HttpApiAnnotator, you must be able to handle the following request and need to respond accordingly.

POST {endpoint}

Executes an analysis for the given text. This request is made by the Content Quality App, not by the FontoXML editor.

Parameters

Request

The body of the request. This will be send as a Multipart/form-data post.

Parameter type

body

Content type

application/json

Model

Body

annotations

Required

Array[Annotation]

The annotations that have been set by earlier annotators.

text

Required

String

The text of the content to analyze.

Annotation

type

Required

AnnotationType

The annotation type identifier.

metadata

Required

Object

Any metadata that is set by the annotator that is relevant for the annotation.

range

Required

Metadata

The range of the annotation within the text.

AnnotationType

name

Required

String

The name of the annotation.

namespace

Required

String

The namespace of the annotation.

AnnotationRange

startIndex

Required

Int

The annotation's starting position within the text.

length

Required

Int

The length of the annotation within the text.

Response

Status

Reason and model

200

The annotations that have been found are returned. This are only the new annotations, NOT the annotations which were set by earlier annotators.

Body

results

Required

Array[Annotation]

The annotations that have been found.

Annotation

type

Required

AnnotationType

The annotation type identifier.

metadata

Required

Object

Any metadata that is set by the annotator that is relevant for the annotation.

The metadata should at least contain some information based upon which two annotations of the same type but having a different meaning can distinguished. For example, if you have an annotator which annotates company names and you have two company names: "FontoXML" and "Liones", and one of the company names can be written in multiple ways but one is preferred, i.e. "FontoXML" and "Fonto", where "FontoXML" is preferred. The following example shows how you can model the metadata:

Found string

metadata

Liones

JavaScript

{
	"somePropertyIndicatingTheCompany": "Liones"
}

FontoXML

JavaScript

{
	"somePropertyIndicatingTheCompany": "FontoXML"
}

Fonto

JavaScript

{
	"somePropertyIndicatingTheCompany": "FontoXML"
}

Note that for the "Fonto" occurrence the property value is "FontoXML" rather than "Fonto", this is because "FontoXML" is the preferred company name, and marks the two annotations as similar. Note that the values could also have been an unique company id, or both an id and the preferred name, or any other metadata which is unique to the company.

Content Quality automatically uses the metadata to detect if found annotations are similar or different, and optimizes the handling and interaction of the annotations in the editor.

You should not include a copy of the found string in the metadata (except if it is indeed the pattern as in the example above) as the editor already has this text in the content, and would also prevent the grouping concepts.

range

Required

Metadata

The range of the annotation within the text.

AnnotationType

name

Required

String

The name of the annotation.

namespace

Required

String

The namespace of the annotation.

AnnotationRange

startIndex

Required

Int

The annotation's starting position within the text.

length

Required

Int

The length of the annotation within the text.

400

Bad Request.

500

Any error in the 500 range indicates a problem with the HttpApiAnnotator.

Examples

Request

JavaScript

{
	"annotations": [
		{
			"range": {
				"startIndex": 0,
				"length": 47
			},
			"metadata": {
				"tag": "en-US"
			},
			"type": {
				"name": "language",
				"namespace": "urn:fontoxml:fcq:annotations:language:1.0.0"
			}
		}
	],
	"text": "An example sentence that needs to be annotated."
}

Response

JavaScript

{
	"results": [
		{
			"type": {
				"name": "my-custom-annotation-name",
				"namespace": "urn:my-custom-annotation-namespace"
			},
			"range": {
				"startIndex": 0,
				"length": 47
			},
			"metadata": {}
		}
	]
}

Example configuration

Example configuration that sends text for analysis together with any build-in language annotation that may be present. It also includes the experimental and optional flag to append the documentId to the request.

XML

<analysis
	xmlns="http://schemas.fontoxml.com/fcq/1.0/analysis-configuration.xsd"
	xmlns:experimental="http://schemas.fontoxml.com/fcq/1.0/experimental-analysis-configuration.xsd"
	xmlns:fl="urn:fontoxml:fcq:annotations:language:1.0.0" >

	<httpApiAnnotator endpoint="https://my-custom-annotator/annotate" inputAnnotationTypeIds="fl:language">
        <experimental:endpointConfiguration>
            <experimental:appendDocumentIdToQueryString/>
        </experimental:endpointConfiguration>
	</httpApiAnnotator>

</analysis>