Document saving, loading, locking, and state management
This describes the endpoints for loading, saving and creating documents, requesting and releasing locks, getting the state of documents periodically, and getting a preview of a document. The response of some of these endpoints may change the Remote document state of a document. Refer to that documentation to see how it will be changed.
Most endpoints support the optional revision
property. Although this property is optional, it SHOULD be implemented when implementing locking. This property should reflect changes in all editable aspects of the document, including its content and metadata.
If revision
is not implemented, remote changes to document content can not be detected, and the editor should not attempt to use locking. In this case, all documents should be returned from the CMS as either available and acquired, or unavailable and not acquired.
G ET /document
This service is used by the Fonto Editor to load all XML documents it needs during an edit session. This includes documents initially loaded, templates and documents for preview.
Parameters
include Additional Documents
Indicates whether additional documents may be included in the response. Its main purpose is to load a multi-document structure with a single request, which would otherwise require several subsequent document load requests. Additional documents typically only include documents from the document structure who’s main purpose is to group and reference other documents e.g. DITA maps. Whether additional documents are included in the response is left to the discretion of the CMS. This property should only be set to true
for initial document load requests. Can be combined with just-in-time loading to minimize document load requests.
The fontoxml-dita add-on sets this property to true
for initial document load requests. For custom multi-document management implementations, this property has to be explicitly implemented for it to be set to true
in the request.
Parameter type |
query |
Type |
boolean |
context ( Required)
The context from which the document was loaded.
Parameter type |
query | ||||||||||||
Model |
|
document Id ( Required)
The document identifier of the XML document to load. This might be a relative url if the requested document is loaded because it is referred to by another document, in this case the referrer
is also specified.
Parameter type |
query |
Type |
string |
Responses
Status |
Reason and model | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
The requested document is returned successfully.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
304 |
The document was not changed since it was last requested and the cached version must be used. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
403 |
The user is not authorized to retrieve the requested document. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
404 |
The document does not exist in the CMS. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
500 |
Any error in the 500 range indicates a problem with the CMS. |
Examples
Request
context |
JavaScript
|
documentId |
74257961-EDE3-4180-AF17-0A435EE8FB7B |
includeAdditionalDocuments |
true |
context |
JavaScript
|
documentId |
74257961-EDE3-4180-AF17-0A435EE8FB7B |
Response
JavaScript
{
"documentId": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />",
"lock": {
"isLockAcquired": true,
"isLockAvailable": true
}
}
JavaScript
{
"documentId": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />",
"lock": {
"isLockAcquired": false,
"isLockAvailable": true
}
}
Other
{
"documentId": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />",
"lock": {
"isLockAcquired": false,
"isLockAvailable": false,
"reason": "This document is currently in use by John Doe. They need to close it before you can reopen and edit it."
}
}
Other
{
"additionalDocuments": [
{
"documentId": "24B376BC-EE0C-44B7-907D-A5DC0788E9E4",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />",
"lock": {
"isLockAcquired": true,
"isLockAvailable": true
}
},
{
"documentId": "47CAF9C7-97B9-43F8-87D8-86AF40216F30",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />",
"lock": {
"isLockAcquired": true,
"isLockAvailable": true
}
}
],
"documentId": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />",
"lock": {
"isLockAcquired": true,
"isLockAvailable": true
}
}
P OS T /document
This service is used if a new document is created within the Fonto Editor. The CMS must store the document and optionally respond the modified content and/or metadata. The document
should be provided by the CMS.
Take special care that the CMS should also automatically give the lock for the document to the editor.
Parameters
body ( Required)
The body object containing initial content and/or metadata, if any. Also contains the context object. The document
is not set since it must be determined by the CMS and lock info is not needed as it should always be opened as if it was is
true.
Parameter type |
body | ||||||||||||||||||||||||||||||||
Content type |
application/json | ||||||||||||||||||||||||||||||||
Model |
|
Responses
Status |
Reason and model | ||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
201 |
The document is created successfully. Optionally the CMS can return modified content and/or metadata which Fonto will load.
| ||||||||||||||||||||||||||||||||||||||||||||
400 |
Fonto provided invalid XML content or invalid/insufficient metadata for the CMS to create the document. | ||||||||||||||||||||||||||||||||||||||||||||
403 |
The user is not authorized to create documents. | ||||||||||||||||||||||||||||||||||||||||||||
409 |
The document could not be created because the document already exists. | ||||||||||||||||||||||||||||||||||||||||||||
500 |
Any error in the 500 range indicates a problem with the CMS. |
Examples
Request
JavaScript
{
"context": {
"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
"referrerDocumentId": "076A86C7-BA00-4AC2-B363-37C454481183"
},
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />"
}
Response
JavaScript
{
"documentId": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />",
"lock": {
"isLockAcquired": true,
"isLockAvailable": true
}
}
P UT /document
This service is used by the Fonto Editor to save a modified XML document and/or its metadata. The CMS must permanently store the new content and metadata. The response of this endpoint will change the Remote document state of a document. Refer to that documentation to see how it will be changed.
Parameters
body ( Required)
The document object to save, including the metadata. Also contains the context object and autosave flag.
Parameter type |
body | ||||||||||||||||||||||||||||||||||||||||
Content type |
application/json | ||||||||||||||||||||||||||||||||||||||||
Model |
|
Responses
Status |
Reason and model | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
The document is saved successfully. The body of the response may contain an updated
| ||||||||||||||||
204 |
The document is saved successfully. The | ||||||||||||||||
400 |
The Fonto Editor provided invalid XML content or invalid/insufficient metadata for the CMS to save the document. The Fonto Editor will warn the user that action is required before the document can be saved. The Fonto Editor will not automatically retry unless the document's content or metadata are changed. This response may optionally contain a body to update the remote state of the document, similar to the /document/state endpoint:
| ||||||||||||||||
403 |
The user is not authorized to access the specified document. The Fonto Editor will warn the user that the document can no longer be accessed and prevent further edits. Use the 412 response if the document can not be saved due to its current lock state and/or an incompatible This response may optionally contain a body to update the remote state of the document, similar to the /document/state endpoint:
| ||||||||||||||||
404 |
The document does not exist in the CMS, and thus cannot be saved. The Fonto Editor will warn the user that the document can no longer be accessed and prevent further edits. | ||||||||||||||||
412 |
The save request failed due to failing preconditions. This can be used to indicate that the document content has changed from that of the given This response may optionally contain a body to update the remote state of the document, similar to the /document/state endpoint. We recommend using this to make the user aware of the reason the request failed, which could be either a mismatching A 412 response must indicate either a revision ID mismatch, an unacquired lock, or both. If the
| ||||||||||||||||
500 |
Any error in the 500 range indicates a problem with the CMS. The Fonto Editor will automatically retry saving the document periodically. |
Examples
Request
JavaScript
{
"context": {
"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE"
},
"documentId": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />"
}
JavaScript
{
"context": {
"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE"
},
"autosave": true,
"documentContext": {
"cmsSpecificDocumentData": "CMS specific value"
},
"documentId": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
"revisionId": "206D7015-B824-4054-BC13-ABAE54D175DF",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />"
}
Response
JavaScript
{
"documentContext": {
"cmsSpecificDocumentData": "CMS specific value"
},
"revisionId": "206D7015-B824-4054-BC13-ABAE54D175DF"
}
P UT /document/lock
This service is used by the Fonto Editor to acquire or release a lock on a given document. The response of this endpoint will change the Remote document state of a document. Refer to that documentation to see how it will be changed.
Parameters
body ( Required)
The information of the requested lock.
Parameter type |
body | ||||||||||||||||||||||||||||||||||||||||
Content type |
application/json | ||||||||||||||||||||||||||||||||||||||||
Model |
|
Responses
Status |
Reason and model | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
The lock has been successfully acquired/released. The body of the response may contain an updated
| ||||||||||||||||
204 |
The lock has been successfully acquired/released. The | ||||||||||||||||
403 |
The user is not authorized to access this document. Use the 412 response if the lock state can not be modified due to the lock being unavailable and/or an incompatible This response may optionally contain a body to update the remote state of the document, similar to the /document/state endpoint:
| ||||||||||||||||
404 |
The document does not exist in the CMS, and thus cannot be interacted with. | ||||||||||||||||
412 |
The lock request failed due to failing preconditions. This can be used to indicate that the document status has changed. The Fonto Editor will warn the user that the document should be reloaded before they can continue editing. This response may optionally contain a body to update the remote state of the document, similar to the /document/state endpoint. We recommend using this to make the user aware of the reason this request failed, which could be either a mismatching A 412 response must indicate either a
| ||||||||||||||||
500 |
Any error in the 500 range indicates a problem with the CMS. |
Examples
Request
JavaScript
{
"context": {
"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE"
},
"documentId": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
"revisionId": "206D7015-B824-4054-BC13-ABAE54D175DF",
"lock": {
"isLockAcquired": true
}
}
Response
JavaScript
{
"documentContext": {
"cmsSpecificDocumentData": "CMS specific value"
},
"revisionId": "206D7015-B824-4054-BC13-ABAE54D175DF"
}
P OS T /document/state
Can be used to periodically retrieve the most recent lock state and revisionId for a set of documents from the CMS. The interval of the requests can be set using the remote-document-state-update-interval-ms configuration variable. The response of this endpoint may change the Remote document states of one or more documents. Refer to that documentation to see how it will be changed.
Parameters
body ( Required)
The information for the state request.
Parameter type |
body | ||||||||||||||||||||||||||||||||
Content type |
application/json | ||||||||||||||||||||||||||||||||
Model |
|
Responses
Status |
Reason and model | ||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
The states have been retrieved successfully. The body contains an array of the states corresponding to the documentIds in the request.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
500 |
Any error in the 500 range indicates a problem with the CMS. |
Examples
Request
JavaScript
{
"context": {
"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE"
},
"documents": [
{
"documentId": "74257961-EDE3-4180-AF17-0A435EE8FB7B"
}
]
}
JavaScript
{
"context": {
"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE"
},
"documents": [
{
"documentId": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
"documentContext": {
"cmsSpecificDocumentData": "CMS specific value"
}
}
]
}
Response
JavaScript
{
"results": [
{
"status": 200,
"body": {
"lock": {
"isLockAcquired": true,
"isLockAvailable": true
}
}
}
]
}
JavaScript
{
"results": [
{
"status": 200,
"body": {
"documentContext": {
"cmsSpecificDocumentData": "CMS specific value"
},
"lock": {
"isLockAcquired": false,
"isLockAvailable": true,
"reason": "This document is currently in use by John Doe. They need to close it before you can reopen and edit it."
},
"revisionId": "206D7015-B824-4054-BC13-ABAE54D175DF"
}
}
]
}
G ET /document/preview
Retrieve a preview of a document from the CMS. The CMS must return a result that can be displayed by the browser in an iframe. Please also make sure you send appropriate headers, like Content-Type.
Parameters
context ( Required)
The context from which the document was loaded.
Parameter type |
query | ||||||||
Model |
|
document Id ( Required)
The document identifier of the document to load the preview of.
Parameter type |
query |
Type |
string |
force Download
Optional parameter used to request a forced download response from the CMS, when this parameter is true it should be used to set the "Content-Disposition" to "attachment" in the response.
Parameter type |
query |
Type |
boolean |
variant
Optional parameter used to request a specific preview variant, can contain arbitrary content as implemented in the operations defined in fontoxml-publication-preview.
Parameter type |
query |
Type |
string |
Responses
Status |
Reason |
---|---|
200 |
The requested document preview is returned successfully. |
304 |
The file has not been changed. Should be handled by browser caching. |
403 |
The user is not authorized to retrieve the document. |
404 |
The document does not exist in the CMS. |
500 |
Any error in the 500 range indicates a problem with the CMS. |
Examples
Request
context |
JavaScript
|
ocumentId |
74257961-EDE3-4180-AF17-0A435EE8FB7B |
P OS T /document/presearch
This document describes an optional endpoint for the Find &
Parameters
body ( Required)
The information for the presearch request.
Parameter type |
body | ||||||||||||||||||||||||||||||||
Content type |
application/json | ||||||||||||||||||||||||||||||||
Model |
|
Responses
Status |
Reason and model | ||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200 |
The presearch was performed successfully.
| ||||||||||||||||||||||||||||||||
500 |
An error occurred during the presearch. |
Examples
Request
JavaScript
{
"context": {
"editSessionToken": "session-63ae-ffef"
},
"documentIds": [
"doc-1-dac3",
"doc-2-353f",
"doc-3-8b0f"
],
"query": {
"fulltext": "paracetamol"
}
}
Response
JavaScript
{
"results": [
{
"status": 200,
"body": {
"documentId": "doc-1-dac3",
"revisionId": "version-1870-f5cd"
}
},
{
"status": 500,
"body": {
"documentId": "doc-3-8b0f"
}
}
]
}
-
Includes a result with status code "200" for the first document because it matches the search query.
-
Omits a result where the documentId is that of the second document because it does not match the search query.
-
Includes a result with status code "500" for the third document because it could not be searched for an unknown reason.