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

body (Required)

Parameter type body
Content type application/json
Model
Body
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
editSessionToken required string Uniquely identifies the instance of FontoXML. See Invocation of the Fonto Editor for details.

Responses

Status Reason and model

200

The annotation identifiers are returned.

Body
results required ReviewStateResult[] The ReviewStateResults for the given documentId(s).
ReviewStateResult
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
id required string The identifier of the Annotation.
revisionId required string The revision identifier of the Annotation corresponding to the annotationId.
400 Bad Request.
5XX Any error in the 500 range indicates a problem with the CMS.

Examples

Request

  Minimal request with filter set to "show unresolved"
{
    "context": {
        "editSessionToken": "3531b216-8952-44f1-b8f9-dda55772253b"
    },
    "documentIds": ["our-products.xml"],
    "filterFormValueByName": {
        "resolutionUnresolved": true
    }
}

Response

  Typical response
{
    "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

body (Required)

Parameter type body
Content type application/json
Model
Body
context required Context The context for this request.
annotationIds required string[] The annotation identifiers of the annotations to get the data for.
Context
editSessionToken required string Uniquely identifies the instance of FontoXML. See Invocation of the Fonto Editor for details.

Responses

Status Reason and model

200

The annotations are returned.

Body
annotations required AnnotationWithStatus[] The Annotations for the given annotationId(s).
AnnotationWithStatus
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
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
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)
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)
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)
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
id required string The identifier.
displayName required string The display name of this author.
400

Bad Request.

403

The user is not authorized to execute this operation.

5XX

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


Examples

Request

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

Response

  Typical response
{
    "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
Model
Body
context required Context The context for this request.
annotation required Annotation The annotation to add.
Context
editSessionToken required string Uniquely identifies the instance of FontoXML. See Invocation of the 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
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)
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)
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)
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 Reason and model

201

The added annotation is returned.

Body
annotation required Annotation The created Annotation.
Annotation
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)
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)
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)
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
id required string The identifier.
displayName required string The display name of this author.
400 Bad Request.
403

The user is not authorized to execute this operation.

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

Examples

Request

  Minimal request
{
    "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

  Typical response
{
    "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
Model
Body
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
editSessionToken required string Uniquely identifies the instance of FontoXML. See Invocation of the Fonto Editor for details.
AnnotationIdentifier
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
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 Reason and model

201

The added reply is returned.

Body
revisionId required string The updated revisionId property of the Annotation corresponding to the added reply.
reply required Reply The created Reply.
Reply
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
id required string The identifier.
displayName required string The display name of this author.
400 Bad Request.
403

The user is not authorized to execute this operation.

404 The annotation to create the reply for does not exist anymore.
412 The revisionId in the request does not match the latest revisionId in the CMS.
5XX Any error in the 500 range indicates a problem with the CMS.

Examples

Request

  Minimal request
{
    "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

  Typical response
{
    "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
Model
Body
context required Context The context for this request.
annotations required Annotation[] The annotations to edit.
Context
editSessionToken required string Uniquely identifies the instance of FontoXML. See Invocation of the 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
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)
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)
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)
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
id required string The identifier.
displayName required string The display name of this author.

Responses

Status Reason and model

200

The edited annotation is returned.

Body
annotations required AnnotationWithStatus[] The edited annotations with their status code.
AnnotationWithStatus
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
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)
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)
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)
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
id required string The identifier.
displayName required string The display name of this author.
400 Bad Request.
403

The user is not authorized to execute this operation.

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

Examples

Request

  Minimal request
context
{ "editSessionToken": "74257961-EDE3-4180-AF17-0A435EE8FB7B" }
annotations
{
    "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

  Typical response
{
    "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
Model
Body
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
editSessionToken required string Uniquely identifies the instance of FontoXML. See Invocation of the Fonto Editor for details.
AnnotationIdentifier
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
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
id required string The identifier.
displayName required string The display name of this author.

Responses

Status Reason and model

200

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

Body

revisionId

required string The updated revisionId property of the Annotation corresponding to the edited reply.
reply required Reply The edited Reply.
Reply
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
id required string The identifier.
displayName required string The display name of this author.
400 Bad Request.
403

The user is not authorized to execute this operation.

404 The annotation to edit the reply for does not exist anymore.
412 The revisionId in the request does not match the latest revisionId in the CMS.
5XX Any error in the 500 range indicates a problem with the CMS.

Examples

Request

  Minimal request
{
    "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

  Typical response
{
    "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

Model
context
editSessionToken required string

Uniquely identifies the instance of FontoXML. See Invocation of the 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.

Was this page helpful?