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 revisionId 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 revisionId 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.

GET /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

includeAdditionalDocuments

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

context

editSessionToken

required

string

Uniquely identifies the instance of FontoXML. See Invocation of the FontoXML editor for details.

referrerDocumentId

optional

string

The documentId of the document referring to the document being requested. This happens when loading topics from a map in DITA for example.

documentId (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 referrerDocumentId is also specified.

Parameter type

query

Type

string

Responses

Status

Reason and model

200

The requested document is returned successfully.

Body

additionalDocuments

optional

array[DocumentResponse]

Any additional documents to process during the initial document load. Should only contain documents when includeAdditionalDocuments is set to true in the request.

documentContext

optional

DocumentContext

CMS-specific data associated with the document. Will be included in related requests.

documentId

required

string

The id of the document.

revisionId

optional

string

An identifier for the revision of the document that is returned.

content

required

string

The actual XML document content.

Make sure to read the Whitespace Handling documentation to comply with our whitespace rules.

lock

required

Lock

Lock state information.

metadata

optional

Metadata

Additional metadata, that is not included inside the XML document itself.

DocumentResponse

status

required

number

The response status, as HTTP status code. Currently, only 200 is supported.

body

required

Document

Matches the response body of GET /document, with the exception of the additionalDocuments property.

Lock

isLockAcquired

required

boolean

Indicates if a lock is acquired for the document. May be false on initial load.

isLockAvailable

required

boolean

Indicates if a lock can be acquired by the user for this document at the time of loading. If the lock is already acquired, this property will always be true. Otherwise, it might be false if the user is not allowed to edit the document or the document is already locked by someone else.

reason

optional

string

Provides additional information to be displayed to the user on why a lock could not be acquired.

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

{
	"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
	"referrerDocumentId": "076A86C7-BA00-4AC2-B363-37C454481183"
}

documentId

74257961-EDE3-4180-AF17-0A435EE8FB7B

includeAdditionalDocuments

true

context

JavaScript

{
	"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
	"referrerDocumentId": "076A86C7-BA00-4AC2-B363-37C454481183"
}

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
	}
}

POST /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 documentId 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 documentId 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 isLockAcquired true.

Parameter type

body

Content type

application/json

Model

Body

context

required

Context

The context from which the document was loaded.

folderId

optional

string

The id of the folder, if any. For example the folder from which the document was created in the file browser.

content

required

string

The actual XML document content.

metadata

optional

Metadata

Additional metadata, that is not included inside the XML document itself.

Context

editSessionToken

required

string

Uniquely identifies the instance of the Fonto editor. See Invocation of the Fonto Editor for details.

referrerDocumentId

optional

string

The documentId of the document referring to the document being requested. This happens when loading topics from a map in DITA for example.

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.

Body

documentContext

optional

DocumentContext

CMS-specific data associated with the document. Will be included in related requests.

documentId

required

string

The id of the document.

revisionId

optional

string

An identifier for the revision of the document that is returned.

content

required

string

The actual XML document content.

lock

required

Lock

Lock state information.

metadata

optional

Metadata

Additional metadata, that is not included inside the XML document itself.

Lock

isLockAcquired

required

boolean

Indicates if a lock is acquired for the document. Should be true for new documents, but make sure you also actually acquire the lock in this case.

isLockAvailable

required

boolean

Indicates if a lock can be acquired. Should be true for new documents.

reason

optional

string

Provides additional information to be displayed to the user on why a lock could not be acquired.

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
	}
}

PUT /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

Body

context

required

Context

The context from which the document was loaded.

autosave

optional

boolean

Indicates if the save was trigger by the auto-save mechanism.

documentContext

optional

DocumentContext

The current CMS-specific data associated with the document.

documentId

required

string

The id of the document.

revisionId

optional

string

The identifier for the revision of the document that the changes are based on.

content

required

string

The actual XML document content.

metadata

optional

Metadata

Additional metadata which is not included inside the XML document itself.

Context

editSessionToken

required

string

Uniquely identifies the instance of the Fonto Editor. See Invocation of the Fonto Editor for details.

Responses

Status

Reason and model

200

The document is saved successfully. The body of the response may contain an updated documentContext, revisionId and/or lock state.

Body

documentContext

optional

DocumentContext

Updated CMS-specific data associated with the document. If included, this will replace the documentContext included in future requests.

revisionId

optional

string

An identifier for the revision of the document that was created by this request

lock

optional

Lock

Can be used to communicate an updated lock state to the Fonto Editor.

204

The document is saved successfully. The documentContext, lock state and revisionId are not updated.

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:

Body

revisionId

optional

string

The identifier for the most recent revision of the document. If this differs from the loaded version, the user will need to reload the document before editing.

lock

optional

Lock

The current lock state for the document.

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 revisionId in the request.

This response may optionally contain a body to update the remote state of the document, similar to the /document/state endpoint:

Body

revisionId

optional

string

The identifier for the most recent revision of the document. If this differs from the loaded version, the user will need to reload the document before editing.

lock

optional

Lock

The current lock state for the document.

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 revisionId. The Fonto Editor will warn the user that the document needs to be reloaded (discarding unsaved changes) before editing can continue. It can also indicate that the lock is no longer acquired.

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 revisionId or a change in the lock state. If the response does not include a revisionId, the Fonto Editor will assume that the revision ID has changed.

A 412 response must indicate either a revision ID mismatch, an unacquired lock, or both. If the revisionId returned is the same as the value in the request, the response must include a lock state that has isLockAcquired set to false.

Body

revisionId

optional

string

The identifier for the most recent revision of the document. If this differs from the loaded version, the user will need to reload the document before editing.

lock

optional

Lock

The current lock state for the document.

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"
}

PUT /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

Body

context

required

Context

The context from which the document was loaded.

documentContext

optional

DocumentContext

The current CMS-specific data associated with the document.

documentId

required

string

The id of the document.

revisionId

optional

string

The identifier for the revision of the document as it was loaded from the CMS via the GET /document and POST /document endpoints.

lock

required

Lock

The desired new lock situation of the document.

Context

editSessionToken

required

string

Uniquely identifies the instance of the Fonto Editor. See Invocation of the Fonto Editor for details.

Lock

isLockAcquired

required

boolean

Indicates if a lock should be acquired or released for the document.

Responses

Status

Reason and model

200

The lock has been successfully acquired/released. The body of the response may contain an updated documentContext, revisionId and/or lock state.

Body

documentContext

optional

DocumentContext

Updated CMS-specific data associated with the document. If included, this will replace the documentContext included in future requests.

revisionId

optional

string

An identifier for the revision of the document that was created by this request.

lock

optional

Lock

The current lock state, updated as a result of this request.

It is an error for this lock state to have a different value for isLockAcquired to the one sent in the request.

204

The lock has been successfully acquired/released. The documentContext, other parts of the lock state and the revisionId are not updated.

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 revisionId in the request.

This response may optionally contain a body to update the remote state of the document, similar to the /document/state endpoint:

Body

revisionId

optional

string

The identifier for the most recent revision of the document. If this differs from the loaded version, the user will need to reload the document before editing.

lock

optional

Lock

The current lock state for the document.

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 revisionId or a change in the lock state. If the response does not include a revisionId, the Fonto Editor will assume that the revision ID has changed.

A 412 response must indicate either a revisionId mismatch, a lock state incompatible with the request, or both. If the revisionId returned is the same as the value in the request, the response must include a lock state that has isLockAvailable set to false and/or has isLockAcquired set to the same value as in the request.

Body

revisionId

optional

string

The identifier for the most recent revision of the document. If this differs from the loaded version, the user will need to reload the document before editing.

lock

optional

Lock

The current lock state for the document.

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"
}

POST /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

Body

context

required

Context

The context from which the document was loaded.

documents

required

array[DocumentState]

Context

editSessionToken

required

string

Uniquely identifies the instance of the Fonto Editor. See Invocation of the Fonto Editor for details.

DocumentState

documentId

required

string

The id of the document

documentContext

optional

DocumentContext

The current CMS-specific data associated with the document.

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.

Body

results

required

array[DocumentStateResponse]

DocumentStateResponse

status

required

number

The result status, uses HTTP status code style. Use 200 for documents which are found and 404 for unknown documents. If it is not possible to perform responses for the full set of documents in a timely manner, the CMS may return 420 for a subset of documents. The Fonto Editor will ignore these results and try again later. Do make sure to return results for a different subset of documents each time, otherwise the editor will not be able to correctly update the state for all documents.

body

optional

DocumentStateWithLock

The requested document state.

DocumentStateWithLock

documentContext

optional

DocumentContext

Updated CMS-specific data associated with the document. If included, this will replace the documentContext included in future requests.

lock

required

Lock

The current lock state for the document.

revisionId

optional

string

The identifier for the most recent revision of the document. If this differs from the loaded version, the client will need to reload the document before editing.

Lock

isLockAcquired

required

boolean

Indicates if a lock is acquired for the document. May be false on initial load.

isLockAvailable

required

boolean

Indicates if a lock can be acquired by the user for this document at the time of loading. If the lock is already acquired, this property will always be true. Otherwise, it might be false if the user is not allowed to edit the document or the document is already locked by someone else.

reason

optional

string

Provides additional information to be displayed to the user on why a lock could not be acquired.

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"
			}
		}
	]
}

GET /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

context

editSessionToken

required

string

Uniquely identifies the instance of the Fonto Editor. See Invocation of the Fonto Editor for details.

documentId (Required)

The document identifier of the document to load the preview of.

Parameter type

query

Type

string

forceDownload

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

{
	"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE"
}

ocumentId

74257961-EDE3-4180-AF17-0A435EE8FB7B

POST /document/presearch

This document describes an optional endpoint for the Find & Replace add-on that the CMS can implement to narrow down the list of documents that necessarily need to be downloaded by the Fonto editor. This endpoint is only applicable for Fonto environments that use both the Find & Replace add-on as well as just-in-time loading as a performance optimization.

Parameters

body (Required)

The information for the presearch request.

Parameter type

body

Content type

application/json

Model

Body

context

required

Context

The context from which the document was loaded.

documentIds

required

array[string]

A list of document ids to search in.

query

required

PresearchQuery

PresearchQuery

fulltext

required

string

The phrase that the user would like to find results for.

Context

editSessionToken

required

string

A value initially given to the Fonto Editor by the CMS and included with every request the Fonto Editor makes so that the broader context of a request can be determined.

Responses

Status

Reason and model

200

The presearch was performed successfully.

Body

results

required

array[PresearchResult]

Represents the documents that (might) match with the given search query.

Documents which do not a match the search query must be omitted from the results.

PresearchResult

status

required

number

The result status, uses HTTP status code style. Use 200 for documents which (might) match the search query, 403 for documents the user has insufficient permissions, 404 for unknown documents, and 500 for documents on which an error occurred while searching.

body

required

PresearchResultBody

PresearchResultBody

documentId

required

string

The RemoteDocumentId for the document this result is about.

revisionId

optional

string

Optional when the status is 404. Otherwise the identifier of the document revision in which a match was found.

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.