Implementation concerns

This section provides information about concerns that need to be thought of when implementing the CMS endpoints of these API contracts.

Caching

In order to reduce network usage and improve the overall load time of the editor, it is recommended that the CMS makes proper use of HTTP caching. Design an efficient caching strategy based on the ETag and If-None-Match headers. See http://en.wikipedia.org/wiki/HTTP_ETag for more information.

Cookies

Fonto Editor does not modify cookies in any way. However it is recommended that cookies set by the CMS have the HttpOnly and Secure flags to ensure Fonto Editor can not access them and they are only sent over HTTPS. See https://www.owasp.org/index.php/HttpOnly and https://www.owasp.org/index.php/SecureFlag for more information.

Security

Fonto Editor is agnostic to authentication and authorization schemes your CMS employs. In most cases this means session or authentication cookies. It is recommend to mark any authentication cookies as HttpOnly and Secure as described above.

Do not use the editSessionToken for any form of authentication or authorization. Its sole purpose is to be able to identify multiple editor instances running in the same authenticated browser session.

Since Fonto Editor runs in the browser on the user’s machine it inherently is, unfortunately, unsafe. The CMS must assume that requests from Fonto Editor are tampered with and should implement appropriate checks to mitigate those risks.

It is recommended to use TLS for all communication between the CMS and Fonto Editor.

URL length limit

Please keep in mind that the URL length may be limited in certain browsers, so a safe limit of 2000 characters for the whole URL including query parameters should be used. The URL length won't be an issue for the endpoints since most of them specify the parameters in the request body. However the Fonto Editor URL with the scope parameter might get too long when loading multiple documents and/or when using long documentIds. Therefore it is important to take this limit into account when designing the CMS backend by identifying the maximum number of documents, the length of the used documentIds and the URL from which Fonto Editor is served.

Content-Type and encoding

All requests and responses between the CMS and Fonto Editor must use the correct Content-Type headers. For most requests, which are JSON objects, application/json must be used as value for the Content-Type header. In case of raw responses used in endpoints, such as GET /asset, POST /asset, and GET /asset/preview, the Content-Type header must use the correct value based on the type of file, e.g. image/jpeg.

All text based requests and responses, including JSON, should be encoded using UTF-8 to work properly with Fonto Editor.

Fonto Editor also sends the correct Accept header and in case of a request body the Content-Type header; These headers will be set to application/json.

Static file compression

To optimize bandwith we recommend to compress the static files that are generated by a Fonto build. Most webservers support compression out of the box but require some configuration. Read more on static file compression here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Compression

Supported image types

Fonto does not have its own image rendering. Instead, it relies on the browser to actually render the image. Consult your browser's documentation for the specifications on image rendering. For more information, see https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types

Autosave

Fonto recommends and defaults to enabling autosave to avoid users losing their work. Autosaving is debounced by 2 seconds after the last edit a user makes in either the DOM or document metadata. It may be postponed slightly further if at that time there are a lot of saves already happening. If an autosave fails, Fonto will try to save again at an increasing interval for a while. After a minute of failed attempts the user is presented with a modal dialogue that explains there is something that has prevented Fonto from saving, and that Fonto will continue to try.

Integration and hosting infrastructure

Fonto Editor does not support CORS (Cross-Origin Resource Sharing). This means that the editor must be hosted on the same domain as where the Fonto Editor standard CMS contracts endpoints are implemented, due to cross-origin policy. This restriction also applies when you use the Fonto Editor iframe CMS connector: the page including the iframe should be hosted on the same origin as the editor.

It is also advisable to host them both on the same domain as the CMS for authentication purposes.

Hosting everything on the same domain can be achieved in multiple ways:

  • Setting up static file hosting for Fonto Editor and implementing the required APIS on the same host, preferably in the CMS itself.

  • Adding a proxy on the domain where the CMS is hosted, which proxies both Fonto Editor and the Fonto Editor standard CMS contracts endpoints to the domain where they are implemented.

  • Adding a proxy on the domain where the CMS is hosted, which proxies Fonto Editor to the domain where the static files are hosted, and proxies the Fonto Editor standard CMS contracts endpoints to the domain where they are implemented.

  • Adding a main proxy in front of everything, which proxies the CMS, Fonto Editor, and Fonto Editor standard CMS contracts to where they are hosted respectively.

When implementing the Fonto Editor standard CMS contracts endpoints on a server proves difficult, you could use the Fonto Editor iframe CMS connector which is a wrapper around the Fonto Editor standard CMS contracts which sends the requests using HTML5 Web Messaging instead of making HTTP requests.