Document saving, loading, locking, and state management

GET /document

This service is used by 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.

context
parameter	required	type	description
editSessionToken	required	string	Uniquely identifies the instance of Fonto Editor. See Invocation of 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.

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 code 200

The requested document is returned successfully.

body
parameter	required	type	description
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
parameter	required	type	description
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
parameter	required	type	description
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.

Status code 304

The document was not changed since it was last requested and the cached version must be used.

Status code 403

The user is not authorized to retrieve the requested document.

Status code 404

The document does not exist in the CMS.

Status code 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": [
		{
			"status": 200,
			"body": {
				"documentId": "24B376BC-EE0C-44B7-907D-A5DC0788E9E4",
				"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />",
				"lock": {
					"isLockAcquired": true,
					"isLockAvailable": true
				}
			}
		},
		{
			"status": 200,
			"body": {
				"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 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

body
parameter	required	type	description
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
parameter	required	type	description
editSessionToken	required	string	Uniquely identifies the instance of Fonto Editor. See Invocation of 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 code 201

The document is created successfully. Optionally the CMS can return modified content and/or metadata which Fonto Editor will load.

body
parameter	required	type	description
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
parameter	required	type	description
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.

Status code 400

Fonto Editor provided invalid XML content or invalid/insufficient metadata for the CMS to create the document.

Status code 403

The user is not authorized to create documents.

Status code 409

The document could not be created because the document already exists.

Status code 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 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

body
parameter	required	type	description
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
parameter	required	type	description
editSessionToken	required	string	Uniquely identifies the instance of Fonto Editor. See Invocation of Fonto Editor for details.

Responses

Status code 200

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

body
parameter	required	type	description
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 Fonto Editor.

Status code 204

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

Status code 400

Fonto Editor provided invalid XML content or invalid/insufficient metadata for the CMS to save the document. The editor will warn the user that action is required before the document can be saved. The 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
parameter	required	type	description
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.

Status code 403

The user is not authorized to access the specified document. 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
parameter	required	type	description
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.

Status code 404

The document does not exist in the CMS, and thus cannot be saved. Fonto Editor will warn the user that the document can no longer be accessed and prevent further edits.

Status code 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. 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, 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
parameter	required	type	description
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.

Status code 500

Any error in the 500 range indicates a problem with the CMS. 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 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

body
parameter	required	type	description
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
parameter	required	type	description
editSessionToken	required	string	Uniquely identifies the instance of Fonto Editor. See Invocation of Fonto Editor for details.

lock
parameter	required	type	description
isLockAcquired	required	boolean	Indicates if a lock should be acquired or released for the document.

Responses

Status code 200

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

body
parameter	required	type	description
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.

Status code 204

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

Status code 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
parameter	required	type	description
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.

Status code 404

The document does not exist in the CMS, and thus cannot be interacted with.

Status code 412

The lock request failed due to failing preconditions. This can be used to indicate that the document status has changed. 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, 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
parameter	required	type	description
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.

Status code 500

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

Status	Reason and model
412
500

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

body
parameter	required	type	description
context	required	Context	The context from which the document was loaded.
documents	required	array[DocumentState]

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

DocumentState
parameter	required	type	description
documentId	required	string	The id of the document
documentContext	optional	DocumentContext	The current CMS-specific data associated with the document.

Responses

Status code 200

The states have been retrieved successfully. The body contains an array of the states corresponding to the documentIds in the request.

body
parameter	required	type	description
results	required	array[DocumentStateResponse]

DocumentStateResponse
parameter	required	type	description
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. 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
parameter	required	type	description
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
parameter	required	type	description
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.

Status code 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.

context
parameter	required	type	description
editSessionToken	required	string	Uniquely identifies the instance of Fonto Editor. See Invocation of 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 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

body
parameter	required	type	description
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
parameter	required	type	description
fulltext	required	string	The phrase that the user would like to find results for.

Context
parameter	required	type	description
editSessionToken	required	string	A value initially given to Fonto Editor by the CMS and included with every request the editor makes so that the broader context of a request can be determined.

Responses

Status code 200

The presearch was performed successfully.

body
parameter	required	type	description
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
parameter	required	type	description
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
parameter	required	type	description
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.

Status code 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.