Document History (BETA)

This describes the endpoints for FontoDocument History.

Fonto Document History is an complementary app to Fonto Editor. When integrating Fonto Document History in the Fonto Editor, these endpoints also need to be implemented in the CMS.

Also note that all identifiers of documents and their revisions must be unique across the CMS. This includes identifiers for private working copies.

GET /document/history

Gets the complete revision history for the given document id in a chronological descending (new to old) order. Not the editor, but the Document History app will execute this request.

Parameters

documentId (Required)

The identifier of the document for which to retrieve the history.

Parameter type

query

Type

string

Fonto-Correlation-Id

The correlation identifier can be used to correlate the request to the request made through the proxy and will only be present if appended to the proxied request.

Parameter type

header

Type

string

Accept (Required)

The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand. See the MDN Web Docs for more information.

Parameter type

header

Type

string

Value

application/json

Responses

Status code 200

The history is returned.

body

parameter

required

type

description

revisions

required

array[Revision]

The Revisions in a chronological descending (new to old) order.

initialFromRevisionId

optional

string

The identifier of the starting revision from which the history is displayed initially. If no value is provided, current minus one is used.

newestRevisionIsWorkingCopy

optional

boolean

If the newest revision is the working copy for the current user. The changes of this revision will be automatically be marked as seen.

Defaults to false, it is recommended to implement this when using the review feature.

Revision

parameter

required

type

description

id

required

string

The identifier of the revision.

author

required

Author

The author.

lastModifiedTimestamp

required

string

The last modified date in ISO 8601.

Author

parameter

required

type

description

id

required

string

The identifier of the author.

displayName

required

string

The display name.

Status code 400

Bad Request.

Status code 401

Authentication failed using the Fonto-Correlation-Id.

Status code 403

Authorization failed using the Fonto-Correlation-Id.

Status code 404

The document could not be found.

Status code 500

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

Examples

Request

documentId

74257961-EDE3-4180-AF17-0A435EE8FB7B

Response

JavaScript

{
	"revisions": [
		{
			"id": "E600FB25-B344-4A15-BDBC-E9CC87F3CE29",
			"author": {
				"id": "user-2",
				"displayName": "Mr. Author 2"
			}
			"lastModifiedTimestamp": "2017-02-17T10:05:03.533Z"
		},
		{
			"id": "1EA1F8A3-DFBB-405A-B479-AFD58EAF8003",
			"author": {
				"id": "user-1",
				"displayName": "Ms. Author 1"
			},
			"lastModifiedTimestamp": "2017-03-14T11:29:38.013Z"
		}
	]
}

GET /document/revision

Gets the XML content of a specific document revision. Not the editor, but the Document History App will execute this request.

Parameters

documentId (Required)

The identifier of the document for which to retrieve the revision.

Parameter type

query

Type

string

revisionId (Required)

The identifier of the revision to retrieve.

Parameter type

query

Type

string

Fonto-Correlation-Id

The correlation identifier can be used to correlate the request to the request made through the proxy and will only be present if appended to the proxied request.

Parameter type

header

Type

string

Accept (Required)

The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand. See the MDN Web Docs for more information.

Parameter type

header

Type

string

Value

application/json

Responses

Status code 200

The revision content is returned.

body

parameter

required

type

description

content

required

string

The XML content of the revision.

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

Status code 400

Bad request.

Status code 401

Authentication failed using the Fonto-Correlation-Id.

Status code 403

Authorization failed using the Fonto-Correlation-Id.

Status code 404

The document or revision could not be found.

Status code 500

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

Examples

Request

documentId

74257961-EDE3-4180-AF17-0A435EE8FB7B

revisionId

E600FB25-B344-4A15-BDBC-E9CC87F3CE29

Response

JavaScript

{
	"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />"
}

GET /document/compare

Endpoint for the Document Compare feature. This endpoint gets the revision data for 2 revisions of 2 documents. Not the editor, but the Document History app will execute this request.

Parameters

documentAId (Required)

The identifier of the document A for which to retrieve the revision identified by documentARevisionId.

Parameter type

query

Type

string

documentARevisionId (Required)

The identifier of the revision to retrieve for document A.

Parameter type

query

Type

string

documentBId (Required)

The identifier of the document B for which to retrieve the revision identified by documentBRevisionId.

Parameter type

query

Type

string

documentBRevisionId (Required)

The identifier of the revision to retrieve for document B.

Parameter type

query

Type

string

Fonto-Correlation-Id

The correlation identifier can be used to correlate the request to the request made through the proxy and will only be present if appended to the proxied request.

Parameter type

header

Type

string

Accept (Required)

The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand. See the MDN Web Docs for more information.

Parameter type

header

Type

string

Value

application/json

Responses

Status code 200

The history is returned.

Body

parameter

required

type

description

documentARevision

required

Revision

The revision data for document A.

documentBRevision

required

Revision

The revision data for document B.

Revision

parameter

required

type

description

author

required

Author

The author.

content

required

string

The revision content

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

lastModifiedTimestamp

required

string

The last modified date in ISO 8601.

Author

parameter

required

type

description

id

required

string

The identifier of the author.

displayName

required

string

The display name.

Status code 400

Bad Request.

Status code 401

Authentication failed using the Fonto-Correlation-Id.

Status code 403

Authorization failed using the Fonto-Correlation-Id.

Status code 404

The document could not be found.

Status code 500

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

Examples

Request

documentAId

74257961-EDE3-4180-AF17-0A435EE8FB7B

documentARevisionId

48957881-BDE5-4AS0-AG89-0D68A78BB945

documentBId

871C70FD-E0CC-4ED3-93CA-F6A6280C339F

documentBRevisionId

B40DB5DD-5C0C-463C-82A9-040A36E163A1

Response

JavaScript

{
	"documentARevision": {
		"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />",
		"author": {
			"id": "fontoxml",
			"displayName": "Jan (Technical writer)"
		},
		"lastModifiedTimestamp": "2017-05-15T12:32:04.152Z"
	},
	"documentBRevision": {
		"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root />",
		"author": {
			"id": "fontoxml",
			"displayName": "John (VP Marketing)"
		},
		"lastModifiedTimestamp": "2017-05-15T12:46:28.474Z"
	}
}

GET /proxy/document-history

Proxies all the requests including the route (excluding the '/proxy/document-history' path, including the subsequent path), headers and query parameters with its payload to the Fonto Document History endpoint. Optionally, a 'Fonto-Correlation-Id' header can be appended to the proxied requests that will be used by Fonto Document History in subsequent requests to the CMS.

Parameters

context (Required)

The context from which the document was loaded.

Parameter type

query

context

parameter

required

type

description

editSessionToken

required

string

Uniquely identifies the instance of Fonto Editor. 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.

Examples

A request made to this endpoint, with subpath /changelog, with the following parameters:

Other

/proxy/document-history/changelog?context={"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE"}&documentId=AB8A37F6-FA34-46A6-AB44-28A07ABF5BBD&revisionId=043FD60A-0386-45EB-9F6D-83C3547AB51C

Should be proxied to:

Other

[document-history-url]/changelog?context={"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE"}&documentId=AB8A37F6-FA34-46A6-AB44-28A07ABF5BBD&revisionId=043FD60A-0386-45EB-9F6D-83C3547AB51C

Optionally with a Fonto-Corrolation-Id header which is used in all related calls to GET /document/history and GET /document/revision.