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.
P OS T /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 |
|
Responses
Status |
Reason and model | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
The annotation identifiers are returned.
| ||||||||||||||||||||||||||||||||||||
400 |
Bad Request. | ||||||||||||||||||||||||||||||||||||
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"
}
]
}
]
}
P OS T /review/annotation/get
Gets the annotation data for each given annotation identifier.
Parameters
body ( Required)
Parameter type |
body | ||||||||||||||||||||
Content type |
application/json | ||||||||||||||||||||
Model |
|
Responses
Status |
Reason and model | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
The annotations are returned.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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
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"
}
}
]
}
P OS T /review/annotation
Create the given annotation.
Parameters
body ( Required)
Parameter type |
body | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Content type |
application/json | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Model |
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.
|
Responses
Status |
Reason and model | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
201 |
The added annotation is returned.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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
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"
}
}
P OS T /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 |
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.
|
Responses
Status |
Reason and model | ||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
201 |
The added reply is returned.
| ||||||||||||||||||||||||||||||||||||||||||||||||
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
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"
}
}
P UT /review/annotation
Edit the given annotation(s).
Parameters
body ( Required)
Parameter type |
body | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Content type |
application/json | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Model |
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"):
|
Responses
Status |
Reason and model | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
The edited annotation is returned.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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
context |
{ "editSessionToken": "74257961-EDE3-4180-AF17-0A435EE8FB7B" } |
annotations |
JavaScript
|
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"
}
}
]
}
P UT /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 |
|
Responses
Status |
Reason and model | ||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
The edited reply and the updated Annotation revision identifier are returned.
| ||||||||||||||||||||||||||||||||||||||||||||||||
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
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"
}
}
XX X /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 |
|
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.