Scrivito as a Headless CMS: The REST API

Scrivito as a Headless CMS: The REST API

A brief introduction to headless CMSs

Scrivito includes a RESTful API for retrieving and updating content from within any application able to issue web requests, e.g. mobile applications. This fully qualifies Scrivito as a headless CMS even though it comes with a WYSIWYG editing interface.

A headless CMS provides an API for accessing the content stored in a repository. It does not provide the means to present this content, i.e. to visualize it and make it accessible to the audience. This makes a headless CMS an ideal solution in situations where, due to special requirements or the diversity of the platforms to address, standard presentation technology cannot be applied and thus tailored interfaces (heads) are needed.

With a headless CMS, having a flexible content maintenance tool as one of its heads is essential. If the same content is to be used on platforms that are different with respect to their capabilities, operability, etc., special fields or attributes may be required to control where which pieces of content should be used in which way.

With Scrivito, such requirements can be met easily due to customizable object classes (content models), its standard output format (JSON), and an easy-to-use in-place editing interface for maintaining all aspects of the content. All you would need is a minimalistic custom web application for browsing the content.

  • Before you start, think about using the Scrivito SDK instead of the REST API wherever this is possible, specifically if you are using Scrivito in a Node.js environment.

    Provided that Scrivito.load is used to obtain the data needed, the SDK optimizes all access to this data, eliminating the need to deal with low-level aspects as it handles temporary errors with API calls gracefully, e.g. by retrying automatically, and loads data efficiently by combining several similar queries into fewer actual REST API requests.

Scrivito’s RESTful API

To issue an API request, you require the ID of the CMS (the tenant) to query, represented as the :tenant_id part in the URL templates below. :tenant_id is a placeholder for your personal tenant ID. Replace all :-prefixed placeholders with a concrete value. For querying CMS resources, you require their respective ID which is also represented in the URL. The data is returned in JSON format.

Authentication

For read access to the published and unrestricted content of a CMS, no authentication is required. Example:

Access to working copies and changes to resources require authentication. You can obtain the API token of your CMS tenant via its “Settings” tab in your account, section “REST API Keys”. API requests that are authorized via an API token have full permissions on all resources of your CMS. Here’s an example of a token-authenticated request, with MYTOKEN as the token:

Datetime format

Dates and times are strings in the “%Y%m%d%H%M%S” format, for example, “20170704154214” represents 2017, July 4th, 15 hours, 42 minutes, 14 seconds. The timezone is always UTC. In JSON, this date and time value looks like this:

Error responses

Errors are reported with a 4xx HTTP code and are JSON objects containing the error details. Every error response includes a human-readable error message. Some errors also have a symbolic code that can be used to check for specific error cases.

Some errors include further details, for example validation errors: