References (connectors)

This describes the endpoints for retrieving and creating references, and updating metadata for existing references.

POST /reference/get

This method returns the details the given references given a permanent identifiers to the references.

Parameters

body (Required)

The details of the references to retrieve.

Parameter type

body

Content type

application/json

Model

Body

context

required

Context

The context of the edit session.

permanentIds

required

array[string]

Context

editSessionToken

required

string

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

Responses

Status

Reason and model

200

The references were successfully retrieved.

Body

results

required

array[ReferenceResponse]

ReferenceResponse

status

required

number

The result status, uses HTTP status code style. Use 200 for references which are found and 404 for unknown references.

body

optional

Reference

The requested reference item.

Reference

permanentId

required

string

The permanent identifier of the reference.

target

required

string

The actual target of the reference.

type

required

string

The type of the reference. Usually web or document.

metadata

optional

Metadata

Additional metadata about the reference. The actual content of this object is application and reference type specific.

500

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

Examples

Request

JavaScript

{
	"context": {
		"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE"
	},
	"permanentIds": [
		"680258CB-B299-4955-B8C2-9ED44D11EF95"
	]
}

Response

JavaScript

{
	"results": [
		{
			"status": 200,
			"body": {
				"permanentId": "680258CB-B299-4955-B8C2-9ED44D11EF95",
				"target": "https://fontoxml.com",
				"type": "web"
			}
		}
	]
}

POST /reference/create

This method creates a new reference in the reference repository and returns the permanent identifier of the newly created reference.

Parameters

body (Required)

The details of the reference which to create.

Parameter type

body

Content type

application/json

Model

Body

context

required

Context

The context of the edit session.

target

required

string

The actual target of the reference.

type

required

string

The type of the reference. Usually web or document.

metadata

optional

Metadata

Additional metadata about the reference. The actual content of this object is application and reference type specific.

Context

editSessionToken

required

string

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

referrerDocumentId

optional

string

The id of the document in which the reference is created. This documentId MUST NOT be used for purposes other then to make the target of the reference absolute. Do NOT use this property to determine where the reference is used, as the resulting permanentId might be used in mulitple documents and thus should be context free.

Responses

Status

Reason and model

201

The reference was successfully created.

Reference

permanentId

required

string

The permanent identifier of the reference.

target

required

string

The actual target of the reference.

type

required

string

The type of the reference. Usually web or document.

metadata

optional

Metadata

Additional metadata about the reference. The actual content of this object is application and reference type specific.

500

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

Examples

Request

JavaScript

{
	"context": {
		"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE"
	},
	"target": "https://fontoxml.com",
	"type": "web"
}

Response

JavaScript

{
	"permanentId": "680258CB-B299-4955-B8C2-9ED44D11EF95",
	"target": "https://fontoxml.com",
	"type": "web"
}

PATCH /reference/metadata/update

This method updates the metadata of an existing reference in the reference repository. Properties can be removed by setting them to null.

Parameters

body (Required)

The details of the reference for which to update the metadata.

Parameter type

body

Content type

application/json

Model

Body

context

required

Context

The context of the edit session.

permanentId

required

string

The permanent identifier of the reference.

metadata

required

Metadata

An object which may contain metadata properties to update or create for the specified reference. Existing properties should be kept; To remove a metadata property, set it to null.

Context

editSessionToken

required

string

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

Metadata

title

optional

string

Highly recommended. The title of the object being referenced.

description

optional

string

A description of the object being referenced.

isSuspicious

optional

boolean

Indicate if the reference is suspicious and needs to be checked by an author.

suspiciousReason

optional

string

The reason to why the reference is invalid. Should be cleared if isSuspicious is set to false.

Responses

Status

Reason and model

200

The reference metadata was successfully updated.

Body

permanentId

required

string

The permanent identifier of the reference.

target

required

string

The actual target of the reference.

type

required

string

The type of the reference. Usually web or document.

metadata

optional

Metadata

Additional metadata about the reference. The actual content of this object is application and reference type specific.

404

The reference identifier by the given permanent identifier was not found in the reference repository.

500

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

Examples

Request

JavaScript

{
	"context": {
		"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE"
	},
	"permanentId": "680258CB-B299-4955-B8C2-9ED44D11EF95",
	"metadata": {
		"title": "FontoXML | Structured Authoring Solutions",
		"isSuspicious": false,
		"suspiciousReason": null
	}
}

Response

Other

{
	"permanentId": "680258CB-B299-4955-B8C2-9ED44D11EF95",
	"target": "https://fontoxml.com",
	"metadata": {
		"title": "FontoXML | Structured Authoring Solutions",
		"description": "FontoXML helps subject matter experts to create structured and highly intelligent content.",
		"isSuspicious": false
	}
}