Help Center

Menu

Content API

Last Updated: 23 Jun 2021

Overview

The Content API lets you use Matrix as a headless CMS through a REST API web service.

As a system administrator, you can control what parts of the asset tree the Content API can access, and what permission restrictions each Content API should inherit based on the user profile selected.

This extension requires a server administrator to install. Please ask your Squiz account manager to find out how to get this extension installed on your Matrix system.

Prerequisites

Read the following prerequisites and information before installing and using the Content API.

Key package information

Minimum supported Matrix version

5.5.4.0

Extension type

Matrix package

Extension version

1.1.4

Installation method

.tgz archive

Availability

Admin mode

Minimum user account level

System Administrator

Installing the extension

This extension is installed using the Matrix package installation process.

You can download the extension package from the Content API Squiz Marketplace listing.

See Matrix Packages for basic installation instructions.

Once you have completed the package installation steps, complete these extra steps to finish the installation process. This extra procedure is only required if you are running Content API on Matrix versions earlier than v5.5.6.0. The feature flag was removed in v5.5.6.0 of Matrix.:

  1. As a server  administrator, edit the feature flags configuration file:
    1. /var/www/squiz_matrix/data/private/conf/feature_flags.inc
  2. Set the SQ_FEATURE_API_ENABLED option to true:
    1. define('SQ_FEATURE_API_ENABLED', true);

Using the extension

You must be a System Administrator or higher to manage Content API access across your Matrix instance.

All Content API tokens are managed through the Content API Manager, which is located under System Management > Content API Manager.

Create tokens beneath this management asset and link the tokens to other root asset nodes you want to access using headless mode.

Field reference

The following fields let you configure what access the API has to your site.

Enabled

Lets you enable or disable this token. If you disable the token, any integrations you have set up using this token will be unavailable.

Requests sent while the token is disabled return a HTTP 401 Unauthorized error when returned in an API request.

Name

The name of the asset displayed in the asset tree. You set this name when you create the token asset.

You can change the name without affecting access to the API endpoint: the asset name is purely to help you locate it in the asset tree.

Token

The API token you use in requests for this content API integration. The token is a unique value, and can not be changed.

User

Select the user to base the permissions of the token against. You can choose any user account type to base the permissions on, depending on the requirements of your API integration.

If you do not select a user, the API returns an HTTP 401 Unauthorized error.

You can also set Root node restrictions to explicitly control what parts of your site are accessible to the API endpoint, in addition to inherited user permissions.

Root node restrictions

Select the root node (or nodes) you want to explicitly grant access to through the API integration, in line with the inherited permissions of the selected user.

If you do not set root node restrictions, the permissions of the selected User determine what assets and resources are available through the API.

Requesting a resource that is not under a restricted root node results in an HTTP 403 Forbidden response being returned.

How to create a Content API token

Tokens can be restricted to assets that are either root nodes, or children of root nodes.

Matrix permissions based on the assigned token user are applied if root node access restrictions are not set against a token.

  1. Click Content API Manager > New Child > Content API Token and set a name for the token.
  2. In the User field, select a user profile from the configured assets.
  3. In the Root Node Restrictions, optionally select one or more assets to apply the access token to.
  4. Click Enabled to set the token to active.
  5. Click Save.
  6. Release the asset locks.

The token asset now has a Token assigned to it. You use this token in an API request to retrieve information from the assets you selected and granted access to.

API reference

The Content API is a read-only (GET) interface: it can not update information stored in Matrix.

Authentication

The Content API uses Authorization Bearer Tokens for authentication. Session-based authentication is not supported.

A token must be sent in a request to the API using an Authorization: Bearer statement.

Authorization: Bearer abcd1234

The “Bearer” statement keyword is case-sensitive. For more information about this statement type, refer to the IETF RFC6750.

A randomly generated unique token value is assigned to the token when the Content API Token asset is created. The token value cannot be changed once it is created.

Error responses

An HTTP 401 Unauthorised response containing a WWW-Authenticate header is returned under the following conditions:

  • The header is malformed
  • The token is invalid because 
    • the asset is disabled or moved into the Trash
    • a user has not been configured against the token.

An HTTP 403 Forbidden response is returned under the following conditions:

  • The user that is configured against the token does not have valid permissions to the requested asset
  • The request is trying to access an asset that is not under an assigned root asset.

An HTTP 404 Not Found response is returned under the following conditions:

  • The requested endpoint does not exist
  • The requested asset does not exist

A 405 Method Not Allowed response is returned when anything other than a GET method verb is used in a request payload.

API documentation

View the Content API Specification for information about the available endpoints with relevant request and response details.

Once the Content API package is installed, endpoint documentation is available from the Content API Manager > Documentation menu within your Matrix instance. This embedded documentation is version-specific. It describes the capabilities of each method offered by the API based on the version you have installed.

If you want to keep the documentation open after you click away from the Content API Manager, click Open in New Window to detach the documentation into a separate browser tab.

Download the specification

You can download the full API specification in OpenAPI v3 format using the Download button within the reference documentation.

Managing the extension

You can manage versions of this extension by upgrading or uninstalling the package.

Upgrading

Upgrading this extension follows the same procedure as the installation process.

Uninstalling

Uninstalling on Matrix servers earlier than v5.5.6.0

Matrix server versions earlier than v5.5.6.0 had support for the Content API behind a feature flag. You need to set the feature flag back to false prior to running the regular removal steps.

To uninstall this extension, you need to have both Matrix system administrator and command-line access to your Matrix instance.

  1. Log in to Matrix as a System Administrator and access admin mode.
  2. Move all Content API Token assets in your Matrix instance to the Trash.
  3. Purge any trashed Content API Token assets from the Trash.
  4. As a Server Administrator, edit the feature flags configuration file:/var/www/squiz_matrix/data/private/conf/feature_flags.inc
  5. Set the SQ_FEATURE_API_ENABLED option to false:
    define('SQ_FEATURE_API_ENABLED', false); 
  6. Open a terminal and navigate into the target Matrix system directory. For example: cd /var/www/squiz_matrix/
  7. Remove the package directory from the Matrix system. For example: rm -rf packages/content_api
  8. Run Step 2 and Step 3 scripts to finalize the package removal process.
    sudo -u apache php install/step_02.php $PWD
sudo -u apache php install/step_03.php $PWD

Uninstalling on Matrix servers later than v.5.5.6.0

To uninstall this extension, you need to have both Matrix system administrator and command-line access to your Matrix instance.

  1. Log in to Matrix as a system administrator and access admin mode.
  2. Move all Content API Token assets in your Matrix instance to the Trash.
  3. Purge any trashed Content API Token assets from the Trash.
  4. Open a terminal and navigate into the target Matrix system directory. For example: cd /var/www/squiz_matrix/
  5. Remove the package directory from the Matrix system. For example: rm -rf packages/package_directory_name
  6. Run Step 2 and Step 3 scripts to finalize the package removal process.
    sudo -u apache php install/step_02.php $PWD
sudo -u apache php install/step_03.php $PWD