Review

This describes the endpoints for the optional Fonto Review add-on.

Besides these endpoints, Fonto Review also requires you to implement the GET /document/history and GET /document/revision endpoints as described in the Document History API reference.

POST /review/state

Get all annotation identifiers for each given documentId. Only return annotations that do not have the status set to "ANNOTATION_STATUS_ARCHIVED".

Only return annotation identifiers that are allowed to be seen by the current user. So, this usually means that private annotations of other users shouldn't be returned.

Parameters

Accept

The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand. See the MDN Web Docs for more information.

Parameter type	header
Type	string
Value	application/json

body (Required)

Parameter type	body
Content type	application/json

body
parameter	required	type	description
documentIds	required	string[]	The identifier of the document(s) for which to retrieve the annotations.
context	required	Context	The context for this request.
filterFormValueByName	required	object	The active filter form values as defined by the application.

Context
parameter	required	type	description
editSessionToken	required	string	Uniquely identifies the instance of Fonto Editor. See Invocation of Fonto Editor for details.

Responses

Status code 200

The annotation identifiers are returned.

Body
parameter	required	type	description
results	required	ReviewStateResult[]	The ReviewStateResults for the given documentId(s).

ReviewStateResult
parameter	required	type	description
annotationIdentifiers	required	AnnotationIdentifier[]	The identifiers of the annotations belonging to this document. Must be an empty array when the value of the status property contains a non 200 status code.
documentId	required	string	The identifier of the document that this ReviewStateResult describes.
status	required	number	The result status. It uses HTTP status code style. Use 200 for documents which are found and 404 for unknown documents.

AnnotationIdentifier
parameter	required	type	description
id	required	string	The identifier of the Annotation.
revisionId	required	string	The revision identifier of the Annotation corresponding to the annotationId.

Status code 400

Bad Request.

Status code 5XX

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

Examples

Request

Other

{
    "context": {
        "editSessionToken": "3531b216-8952-44f1-b8f9-dda55772253b"
    },
    "documentIds": ["our-products.xml"],
    "filterFormValueByName": {
        "resolutionUnresolved": true
    }
}

Response

JavaScript

{
    "results": [{
            "documentId": "our-products.xml",
            "status": 200,
            "annotationIdentifiers": [{
                    "id": "8cd04d1e-ac2f-4a3f-ba7a-84201050ae60",
                    "revisionId": "73d3c50a-c71b-4be5-b735-4ad48eb84fe8"
                }
            ]
        }
    ]
}

POST /review/annotation/get

Gets the annotation data for each given annotation identifier.

Parameters

Accept

The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand. See the MDN Web Docs for more information.

Parameter type	header
Type	string
Value	application/json

body (Required)

Parameter type	body
Content type	application/json

body
parameter	required	type	description
context	required	Context	The context for this request.
annotationIds	required	string[]	The annotation identifiers of the annotations to get the data for.

Context
parameter	required	type	description
editSessionToken	required	string	Uniquely identifies the instance of Fonto Editor. See Invocation of Fonto Editor for details.

Responses

Status code 200

The annotations are returned.

body
parameter	required	type	description
annotations	required	AnnotationWithStatus[]	The Annotations for the given annotationId(s).

AnnotationWithStatus
parameter	required	type	description
annotation	required	Annotation	The Annotation. Only the id and documentId properties of Annotation are required when the status property contains a non 200 status code. If the annotation really is not found, the documentId property can be omitted.
status	required	number	Status for the requested annotation. 200 for annotations that can be found, 404 for unknown annotations.

Annotation
parameter	required	type	description
id	required	string	The identifier.
documentId	required	string	The document identifier for this annotation.
revisionId	required	string	The revision identifier for this annotation.
targets	required	Target[]	The targets for this annotation. Targets have a type property to indicate their type.
replies	required	Reply[]	The replies for this annotation. Must be an empty array when there are no replies. Only return replies that do not have the status set to "REPLY_STATUS_ARCHIVED".
author	required	Author	The creator of this annotation.
timestamp	required	string	The timestamp (ISO 8601) when this annotation was created.
status	required	string	The status of this annotation. Can be either "ANNOTATION_STATUS_PRIVATE", "ANNOTATION_STATUS_SHARED", "ANNOTATION_STATUS_RESOLVED" or "ANNOTATION_STATUS_ARCHIVED".
type	required	string	Application level configured annotation type.
metadata	required	Object	Application level configured annotation metadata.
createdDocumentRevisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the annotation was created.
originalText	required	string	The text this annotations was placed on in the original document revision.
resolvedMetadata	required	Object	Application level configured annotation resolved metadata. Optional when status is not "ANNOTATION_STATUS_RESOLVED".
resolvedAuthor	required	Author	The resolver of the annotation. Optional when status is not "ANNOTATION_STATUS_RESOLVED".
resolvedDocumentRevisionId	required	string	The revision identifier of the document that was loaded in the editor at the time of resolving this annotation. Optional when status is not "ANNOTATION_STATUS_RESOLVED".
resolvedTimestamp	required	string	The timestamp (ISO 8601) when this annotation was resolved. Optional when status is not "ANNOTATION_STATUS_RESOLVED".

Reply
parameter	required	type	description
id	required	string	The identifier.
metadata	required	Object	Application level configured reply metadata.
author	required	Author	The creator of this reply.
status	required	string	The status of this reply. Can be either "REPLY_STATUS_SHARED" or "REPLY_STATUS_ARCHIVED". Replies are created with a status set to shared ("REPLY_STATUS_SHARED") by default.
timestamp	required	string	The timestamp (ISO 8601) when this reply was created.

Target (type is TEXT_RANGE_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
startContainerQuery	required	string	The XPath for the containing node where the start of the annotation is located. For more info on the format, see the "Annotation targets" part of the Fonto Review documentation.
startOffset	required	number	The offset in the containing node where the start of the annotation is located.
endContainerQuery	required	string	The XPath for the containing node where the end of the annotation is located. For more info on the format, see the "Annotation targets" part of the Fonto Review documentation.
endOffset	required	number	The offset in the containing node where the end of the annotation is located.
type	required	string	The type of this target. Is TEXT_RANGE_SELECTOR for text range comments.

Target (type is OBJECT_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
query	required	string	The XPath to the target object node of the annotation.
type	required	string	The type of this target. Is OBJECT_SELECTOR for object comments.

Target (type is PUBLICATION_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
type	required	string	The type of this target. Is PUBLICATION_SELECTOR for publication level comments.

Author
parameter	required	type	description
id	required	string	The identifier.
displayName	required	string	The display name of this author.

Status code 400

Bad Request.

Status code 403

The user is not authorized to execute this operation.

Status code 5XX

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

Examples

Request

Other

{
    "context": {
        "editSessionToken": "c18c7f54-2eec-4051-b8c7-04cdc505a29f"
    },
    "annotationIds": ["8cd04d1e-ac2f-4a3f-ba7a-84201050ae60"]
}

Response

JavaScript

{
    "annotations": [{
            "status": 200,
            "annotation": {
                "documentId": "our-products.xml",
                "originalText": "user",
                "targets": [{
                        "revisionId": "e688e1a2-e3ad-4285-9355-6f20a52b3edf",
                        "startContainerQuery": "/node()[1]/node()[2]/node()[1]/node()[1]",
                        "startOffset": 309,
                        "endContainerQuery": "/node()[1]/node()[2]/node()[1]/node()[1]",
                        "endOffset": 313,
                        "type": "TEXT_RANGE_SELECTOR"
                    }
                ],
                "status": "ANNOTATION_STATUS_PRIVATE",
                "type": "comment",
                "metadata": {
                    "comment": "This is a comment.",
                    "commentType": "general"
                },
                "resolvedMetadata": {},
                "createdDocumentRevisionId": "e688e1a2-e3ad-4285-9355-6f20a52b3edf",
                "author": {
                    "id": "lodejong",
                    "displayName": "Lorenzo de Jong",
                    "roleId": "editor"
                },
                "id": "8cd04d1e-ac2f-4a3f-ba7a-84201050ae60",
                "replies": [],
                "revisionId": "73d3c50a-c71b-4be5-b735-4ad48eb84fe8",
                "timestamp": "2019-09-02T11:14:10.159Z"
            }
        }
    ]
}

POST /review/annotation

Create the given annotation.

Parameters

body (Required)

Parameter type	body
Content type	application/json

body
parameter	required	type	description
context	required	Context	The context for this request.
annotation	required	Annotation	The annotation to add.

Context
parameter	required	type	description
editSessionToken	required	string	Uniquely identifies the instance of Fonto Editor. See Invocation of Fonto Editor for details.

The following properties are omitted from the Annotation model in this request. These properties should be added to the new annotation before storing the annotation.

id
author
timestamp
revisionId
replies

Annotation
parameter	required	type	description
documentId	required	string	The document identifier for this annotation.
targets	required	Target[]	The targets for this annotation. Targets have a type property to indicate their type.
status	required	string	The status of this annotation. Can be either "ANNOTATION_STATUS_PRIVATE", "ANNOTATION_STATUS_SHARED", "ANNOTATION_STATUS_RESOLVED" or "ANNOTATION_STATUS_ARCHIVED".
type	required	string	Application level configured annotation type.
metadata	required	Object	Application level configured annotation metadata.
createdDocumentRevisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the annotation was created.
originalText	required	string	The text this annotations was placed on in the original document revision.
resolvedMetadata	required	Object	Application level configured annotation resolved metadata. Optional when status is not "ANNOTATION_STATUS_RESOLVED".

Target (type is TEXT_RANGE_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
startContainerQuery	required	string	The XPath for the containing node where the start of the annotation is located. For more info on the format, see the "Annotation targets" part of the Fonto Review documentation.
startOffset	required	number	The offset in the containing node where the start of the annotation is located.
endContainerQuery	required	string	The XPath for the containing node where the end of the annotation is located. For more info on the format, see the "Annotation targets" part of the Fonto Review documentation.
endOffset	required	number	The offset in the containing node where the end of the annotation is located.
type	required	string	The type of this target. Is TEXT_RANGE_SELECTOR for text range comments.

Target (type is OBJECT_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
query	required	string	The XPath to the target object node of the annotation.
type	required	string	The type of this target. Is OBJECT_SELECTOR for object comments.

Target (type is PUBLICATION_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
type	required	string	The type of this target. Is PUBLICATION_SELECTOR for publication level comments.

Responses

Status code 201

The added annotation is returned.

body
parameter	required	type	description
annotation	required	Annotation	The created Annotation.

Annotation
parameter	required	type	description
id	required	string	The identifier.
documentId	required	string	The document identifier for this annotation.
revisionId	required	string	The revision identifier for this annotation.
targets	required	Target[]	The targets for this annotation. Targets have a type property to indicate their type.
author	required	Author	The creator of this annotation.
timestamp	required	string	The timestamp (ISO 8601) when this annotation was created.
status	required	string	The status of this annotation. Can be either "ANNOTATION_STATUS_PRIVATE", "ANNOTATION_STATUS_SHARED", "ANNOTATION_STATUS_RESOLVED" or "ANNOTATION_STATUS_ARCHIVED".
type	required	string	Application level configured annotation type.
metadata	required	Object	Application level configured annotation metadata.
createdDocumentRevisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the annotation was created.
originalText	required	string	The text this annotations was placed on in the original document revision.
resolvedMetadata	required	Object	Application level configured annotation resolved metadata. Optional when status is not "ANNOTATION_STATUS_RESOLVED".

Target (type is TEXT_RANGE_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
startContainerQuery	required	string	The XPath for the containing node where the start of the annotation is located. For more info on the format, see the "Annotation targets" part of the Fonto Review documentation.
startOffset	required	number	The offset in the containing node where the start of the annotation is located.
endContainerQuery	required	string	The XPath for the containing node where the end of the annotation is located. For more info on the format, see the "Annotation targets" part of the Fonto Review documentation.
endOffset	required	number	The offset in the containing node where the end of the annotation is located.
type	required	string	The type of this target. Is TEXT_RANGE_SELECTOR for text range comments.

Target (type is OBJECT_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
query	required	string	The XPath to the target object node of the annotation.
type	required	string	The type of this target. Is OBJECT_SELECTOR for object comments.

Target (type is PUBLICATION_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
type	required	string	The type of this target. Is PUBLICATION_SELECTOR for publication level comments.

Author
parameter	required	type	description
id	required	string	The identifier.
displayName	required	string	The display name of this author.

Status code 400

Bad Request.

Status code 403

The user is not authorized to execute this operation.

Status code 5XX

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

Examples

Request

Other

{
    "context": {
        "editSessionToken": "c3ff231a-d173-41a0-8774-c975ccd85ab3"
    },
    "annotation": {
        "documentId": "our-products.xml",
        "originalText": "user",
        "targets": [{
                "revisionId": "e688e1a2-e3ad-4285-9355-6f20a52b3edf",
                "startContainerQuery": "/node()[1]/node()[2]/node()[1]/node()[1]",
                "startOffset": 309,
                "endContainerQuery": "/node()[1]/node()[2]/node()[1]/node()[1]",
                "endOffset": 313,
                "type": "TEXT_RANGE_SELECTOR"
            }
        ],
        "status": "ANNOTATION_STATUS_PRIVATE",
        "type": "comment",
        "metadata": {
            "comment": "This is a comment",
            "commentType": "general"
        },
        "resolvedMetadata": {},
        "createdDocumentRevisionId": "e688e1a2-e3ad-4285-9355-6f20a52b3edf"
    }
}

Response

JavaScript

{
    "annotation": {
        "documentId": "our-products.xml",
        "originalText": "user",
        "targets": [{
                "revisionId": "e688e1a2-e3ad-4285-9355-6f20a52b3edf",
                "startContainerQuery": "/node()[1]/node()[2]/node()[1]/node()[1]",
                "startOffset": 309,
                "endContainerQuery": "/node()[1]/node()[2]/node()[1]/node()[1]",
                "endOffset": 313,
                "type": "TEXT_RANGE_SELECTOR"
            }
        ],
        "status": "ANNOTATION_STATUS_PRIVATE",
        "type": "comment",
        "metadata": {
            "comment": "This is a comment",
            "commentType": "general"
        },
        "resolvedMetadata": {},
        "createdDocumentRevisionId": "e688e1a2-e3ad-4285-9355-6f20a52b3edf",
        "author": {
            "id": "lodejong",
            "displayName": "Lorenzo de Jong",
            "roleId": "editor"
        },
        "id": "ac2bbbd2-537f-4a76-87a2-d31148723dd4",
        "revisionId": "187d9967-5129-430b-9534-d8e7571cc0a1",
        "timestamp": "2019-09-02T11:17:59.389Z"
    }
}

POST /review/annotation/reply

Create the given reply for the specified annotation.

When this request is successful and the reply is added, the corresponding annotation based on the "annotationIdentifier" parameter should also update its "revisionId" property.

Parameters

body (Required)

Parameter type	body
Content type	application/json

body
parameter	required	type	description
context	required	Context	The context for this request.
annotationIdentifier	required	AnnotationIdentifier	The annotationIdentifier for the annotation to create the reply for.
reply	required	Reply	The reply to add.

Context
parameter	required	type	description
editSessionToken	required	string	Uniquely identifies the instance of Fonto. See Invocation of Fonto Editor for details.

AnnotationIdentifier
parameter	required	type	description
id	required	string	The identifier of the Annotation.
documentId	required	string	The identifier of the document that this Annotation belongs to.
revisionId	required	string	The revision identifier of the Annotation corresponding to the id.

The following properties are omitted from the Reply model in this request. These properties should be added to the new reply before storing the reply.

id
author
timestamp

Reply
parameter	required	type	description
metadata	required	Object	Application level configured reply metadata.
status	required	string	The status of this reply. Can be either "REPLY_STATUS_SHARED" or "REPLY_STATUS_ARCHIVED". Replies are created with a status set to shared ("REPLY_STATUS_SHARED") by default.

Responses

Status code 201

The added reply is returned.

body
parameter	required	type	description
revisionId	required	string	The updated revisionId property of the Annotation corresponding to the added reply.
reply	required	Reply	The created Reply.

Reply
parameter	required	type	description
id	required	string	The identifier.
metadata	required	Object	Application level configured reply metadata.
author	required	Author	The creator of this reply.
timestamp	required	string	The timestamp (ISO 8601) when this reply was created.
status	required	string

Author
parameter	required	type	description
id	required	string	The identifier.
displayName	required	string	The display name of this author.

Status code 400

Bad request.

Status code 403

The user is not authorized to execute this operations.

Status code 404

The annotation to create the reply for does not exist anymore.

Status code 412

The revisionId in the request does not match the latest revisionId in the CMS.

Status code 5XX

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

Examples

Request

Other

{
    "context": {
        "editSessionToken": "90590263-5d88-4171-ab67-8c51f61a7862"
    },
    "annotationIdentifier": {
        "id": "267a43d0-ee8f-4eca-b012-e6e10d0ad7b2",
        "documentId": "our-products.xml",
        "revisionId": "1a485e3e-a127-406d-88ec-a6c410646d63"
    },
    "reply": {
        "status": "REPLY_STATUS_SHARED",
        "metadata": {
            "reply": "This is a reply."
        }
    }
}

Response

JavaScript

{
    "revisionId": "b1bddf85-6a9f-45e7-a3dd-861802abfe32",
    "reply": {
        "status": "REPLY_STATUS_SHARED",
        "metadata": {
            "reply": "This is a reply."
        },
        "author": {
            "id": "lodejong",
            "displayName": "Lorenzo de Jong",
            "roleId": "editor"
        },
        "id": "a49ad3a5-abb9-4ab4-a61c-82ce9dffaade",
        "timestamp": "2019-09-02T11:21:26.669Z"
    }
}

PUT /review/annotation

Edit the given annotation(s).

Parameters

body (Required)

Parameter type	body
Content type	application/json

body
parameter	required	type	description
context	required	Context	The context for this request.
annotations	required	Annotation[]	The annotations to edit.

Context
parameter	required	type	description
editSessionToken	required	string	Uniquely identifies the instance of Fonto. See Invocation of Fonto Editor for details.

The "revisionId" property should contain a new unique identifier when the annotation is successfully edited.

The following parameters are omitted from the Annotation in the request and should be added when the annotation is resolved (status is changed to "ANNOTATION_STATUS_RESOLVED"):

resolvedAuthor
resolvedTimestamp

Annotation
parameter	required	type	description
id	required	string	The identifier.
documentId	required	string	The document identifier for this annotation.
revisionId	required	string	The revision identifier for this annotation.
targets	required	Target[]	The targets for this annotation. Targets have a type property to indicate their type.
author	required	Author	The creator of this annotation.
timestamp	required	string	The timestamp (ISO 8601) when this annotation was created.
status	required	string	The status of this annotation. Can be either "ANNOTATION_STATUS_PRIVATE", "ANNOTATION_STATUS_SHARED", "ANNOTATION_STATUS_RESOLVED" or "ANNOTATION_STATUS_ARCHIVED".
type	required	string	Application level configured annotation type.
metadata	required	Object	Application level configured annotation metadata.
createdDocumentRevisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the annotation was created.
originalText	required	string	The text this annotations was placed on in the original document revision.
resolvedMetadata	required	Object	Application level configured annotation resolved metadata. Optional when status is not "ANNOTATION_STATUS_RESOLVED".
resolvedDocumentRevisionId	required	string	The revision identifier of the document that was loaded in the editor at the time of resolving this annotation. Optional when status is not "ANNOTATION_STATUS_RESOLVED".

Target (type is TEXT_RANGE_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
startContainerQuery	required	string	The XPath for the containing node where the start of the annotation is located. For more info on the format, see the "Annotation targets" part of the Fonto Review documentation.
startOffset	required	number	The offset in the containing node where the start of the annotation is located.
endContainerQuery	required	string	The XPath for the containing node where the end of the annotation is located. For more info on the format, see the "Annotation targets" part of the Fonto Review documentation.
endOffset	required	number	The offset in the containing node where the end of the annotation is located.
type	required	string	The type of this target. Is TEXT_RANGE_SELECTOR for text range comments.

Target (type is OBJECT_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
query	required	string	The XPath to the target object node of the annotation.
type	required	string	The type of this target. Is OBJECT_SELECTOR for object comments.

Target (type is PUBLICATION_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
type	required	string	The type of this target. Is PUBLICATION_SELECTOR for publication level comments.

Author
parameter	required	type	description
id	required	string	The identifier.
displayName	required	string	The display name of this author.

Responses

Status code 200

The edited annotation is returned.

body
parameter	required	type	description
annotations	required	AnnotationWithStatus[]	The edited annotations with their status code.

AnnotationWithStatus
parameter	required	type	description
annotation	required	Annotation	The Annotation. Only the id property of Annotation is required when the status property contains a non 200 status code.
status	required	number	Status for the saved annotation. One of: 200, 403, 404, 412.

Annotation
parameter	required	type	description
id	required	string	The identifier.
documentId	required	string	The document identifier for this annotation.
revisionId	required	string	The revision identifier for this annotation.
targets	required	Target[]	The targets for this annotation. Targets have a type property to indicate their type.
author	required	Author	The creator of this annotation.
timestamp	required	string	The timestamp (ISO 8601) when this annotation was created.
status	required	string	The status of this annotation. Can be either "ANNOTATION_STATUS_PRIVATE", "ANNOTATION_STATUS_SHARED", "ANNOTATION_STATUS_RESOLVED" or "ANNOTATION_STATUS_ARCHIVED".
type	required	string	Application level configured annotation type.
metadata	required	Object	Application level configured annotation metadata.
createdDocumentRevisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the annotation was created.
originalText	required	string	The text this annotations was placed on in the original document revision.
resolvedMetadata	required	Object	Application level configured annotation resolved metadata. Optional when status is not "ANNOTATION_STATUS_RESOLVED".
resolvedAuthor	required	Author	The resolver of the annotation. Optional when status is not "ANNOTATION_STATUS_RESOLVED".
resolvedDocumentRevisionId	required	string	The revision identifier of the document that was loaded in the editor at the time of resolving this annotation. Optional when status is not "ANNOTATION_STATUS_RESOLVED".
resolvedTimestamp	required	string	The timestamp (ISO 8601) when this annotation was resolved. Optional when status is not "ANNOTATION_STATUS_RESOLVED".

Target (type is TEXT_RANGE_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
startContainerQuery	required	string	The XPath for the containing node where the start of the annotation is located. For more info on the format, see the "Annotation targets" part of the Fonto Review documentation.
startOffset	required	number	The offset in the containing node where the start of the annotation is located.
endContainerQuery	required	string	The XPath for the containing node where the end of the annotation is located. For more info on the format, see the "Annotation targets" part of the Fonto Review documentation.
endOffset	required	number	The offset in the containing node where the end of the annotation is located.
type	required	string	The type of this target. Is TEXT_RANGE_SELECTOR for text range comments.

Target (type is OBJECT_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
query	required	string	The XPath to the target object node of the annotation.
type	required	string	The type of this target. Is OBJECT_SELECTOR for object comments.

Target (type is PUBLICATION_SELECTOR)
parameter	required	type	description
revisionId	required	string	The revision identifier of the document that was loaded in the editor at the time the target was created.
type	required	string	The type of this target. Is PUBLICATION_SELECTOR for publication level comments.

Author
parameter	required	type	description
id	required	string	The identifier.
displayName	required	string	The display name of this author.

Status code 400

Bad Request.

Status code 403

The user is not authorized to execute this operation.

Status code 5XX

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

Examples

Request

context

{ "editSessionToken": "74257961-EDE3-4180-AF17-0A435EE8FB7B" }

annotations

JavaScript

{
    "context": {
        "editSessionToken": "90590263-5d88-4171-ab67-8c51f61a7862"
    },
    "annotations": [{
            "documentId": "our-products.xml",
            "originalText": " user",
            "targets": [{
                    "revisionId": "e688e1a2-e3ad-4285-9355-6f20a52b3edf",
                    "startContainerQuery": "/node()[1]/node()[2]/node()[1]/node()[1]",
                    "startOffset": 308,
                    "endContainerQuery": "/node()[1]/node()[2]/node()[1]/node()[1]",
                    "endOffset": 313,
                    "type": "TEXT_RANGE_SELECTOR"
                }
            ],
            "status": "ANNOTATION_STATUS_PRIVATE",
            "type": "comment",
            "metadata": {
                "comment": "This is an edited comment.",
                "commentType": "general"
            },
            "resolvedMetadata": {},
            "createdDocumentRevisionId": "e688e1a2-e3ad-4285-9355-6f20a52b3edf",
            "author": {
                "id": "lodejong",
                "displayName": "Lorenzo de Jong",
                "roleId": "editor"
            },
            "id": "267a43d0-ee8f-4eca-b012-e6e10d0ad7b2",
            "revisionId": "b1bddf85-6a9f-45e7-a3dd-861802abfe32",
            "timestamp": "2019-09-02T11:21:17.878Z"
        }
    ]
}

Response

JavaScript

{
    "annotations": [{
            "status": 200,
            "annotation": {
                "documentId": "our-products.xml",
                "originalText": " user",
                "targets": [{
                        "revisionId": "e688e1a2-e3ad-4285-9355-6f20a52b3edf",
                        "startContainerQuery": "/node()[1]/node()[2]/node()[1]/node()[1]",
                        "startOffset": 308,
                        "endContainerQuery": "/node()[1]/node()[2]/node()[1]/node()[1]",
                        "endOffset": 313,
                        "type": "TEXT_RANGE_SELECTOR"
                    }
                ],
                "status": "ANNOTATION_STATUS_PRIVATE",
                "type": "comment",
                "metadata": {
                    "comment": "This is an edited comment.",
                    "commentType": "general"
                },
                "resolvedMetadata": {},
                "createdDocumentRevisionId": "e688e1a2-e3ad-4285-9355-6f20a52b3edf",
                "author": {
                    "id": "lodejong",
                    "displayName": "Lorenzo de Jong",
                    "roleId": "editor"
                },
                "id": "267a43d0-ee8f-4eca-b012-e6e10d0ad7b2",
                "revisionId": "c1d9523e-7592-4452-8b94-37d93d2099f7",
                "timestamp": "2019-09-02T11:21:17.878Z"
            }
        }
    ]
}

PUT /review/annotation/reply

Edit the given reply on the specified annotation.

When this request is successful and the reply is edited, the corresponding annotation based on the "annotationIdentifier" parameter should also update its "revisionId" property.

Parameters

body (Required)

Parameter type	body
Content type	application/json

body
parameter	required	type	description
context	required	Context	The context for this request.
annotationIdentifier	required	AnnotationIdentifier	The AnnotationIdentifier for the annotation to edit the reply for.
reply	required	Reply	The reply to edit.

Context
parameter	required	type	description
editSessionToken	required	string	Uniquely identifies the instance of Fonto. See Invocation of Fonto Editor for details.

AnnotationIdentifier
parameter	required	type	description
id	required	string	The identifier of the Annotation.
documentId	required	string	The identifier of the document that this Annotation belongs to.
revisionId	required	string	The revision identifier of the Annotation corresponding to the id.

Reply
parameter	required	type	description
id	required	string	The identifier.
metadata	required	Object	Application level configured reply metadata.
author	required	Author	The creator of this reply.
timestamp	required	string	The timestamp (ISO 8601) when this reply was created.
status	required	string	The status of this reply. Can be either "REPLY_STATUS_SHARED" or "REPLY_STATUS_ARCHIVED". Replies are created with a status set to shared ("REPLY_STATUS_SHARED") by default.

Author
parameter	required	type	description
id	required	string	The identifier.
displayName	required	string	The display name of this author.

Responses

Status code 200

The edited reply and the updated Annotation revision identifier are returned.

body
parameter	required	type	description
revisionId	required	string	The updated revisionId property of the Annotation corresponding to the edited reply.
reply	required	Reply	The edited Reply.

Reply
parameter	required	type	description
id	required	string	The identifier.
metadata	required	Object	Application level configured reply metadata.
author	required	Author	The creator of this reply.
timestamp	required	string	The timestamp (ISO 8601) when this reply was created.
status	required	string

Author
parameter	required	type	description
id	required	string	The identifier.
displayName	required	string	The display name of this author.

Status code 400

Bad Request.

Status code 403

The user is not authorized to execute this operation.

Status code 404

The annotation to edit the reply for does not exist anymore.

Status code 412

The revisionId in the request does not match the latest revisionId in the CMS.

Status code 5XX

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

Examples

Request

Other

{
    "context": {
        "editSessionToken": "90590263-5d88-4171-ab67-8c51f61a7862"
    },
    "annotationIdentifier": {
        "id": "267a43d0-ee8f-4eca-b012-e6e10d0ad7b2",
        "documentId": "our-products.xml",
        "revisionId": "c1d9523e-7592-4452-8b94-37d93d2099f7"
    },
    "reply": {
        "status": "REPLY_STATUS_SHARED",
        "metadata": {
            "reply": "This is an edited reply."
        },
        "author": {
            "id": "lodejong",
            "displayName": "Lorenzo de Jong",
            "roleId": "editor"
        },
        "id": "a49ad3a5-abb9-4ab4-a61c-82ce9dffaade",
        "timestamp": "2019-09-02T11:21:26.669Z"
    }
}

Response

JavaScript

{
    "revisionId": "beacd3dd-bcee-4495-89a7-6320ffa1ace8",
    "reply": {
        "status": "REPLY_STATUS_SHARED",
        "metadata": {
            "reply": "This is an edited reply."
        },
        "author": {
            "id": "lodejong",
            "displayName": "Lorenzo de Jong",
            "roleId": "editor"
        },
        "id": "a49ad3a5-abb9-4ab4-a61c-82ce9dffaade",
        "timestamp": "2019-09-02T11:21:26.669Z"
    }
}

XXX /proxy/review

All protocols should be supported. However, currently, only the POST method is used.

Proxies all the requests including the route (excluding the '/proxy/review' path, including the subsequent path), headers and query parameters with its payload to the Review App endpoint. Optionally, a 'Fonto-Correlation-Id' header can be appended to the proxied requests that will be used by the Review App in subsequent requests to the CMS.

Parameters

context (Required)

The context from which the document was loaded.

Parameter type	query

context
parameter	required	type	description
editSessionToken	required	string	Uniquely identifies the instance of Fonto Editor. See Invocation of Fonto Editor for details. Note that the editSessionToken will not be sent to the CMS in later requests. Use the Fonto-Correlation-Id header for that.

Responses

Responses depend on which sub path is called. However, the proxy endpoint should return responses as is, without any modification to the HTTP status code, headers, and body.