Content Delivery API Beta

Last Updated: 11 Oct 2019

This feature is still in development and should not be enabled on production instances of Squiz Matrix.

The Content Delivery API is an upcoming new feature for Squiz Matrix that will empower developers to use Matrix as a Headless CMS using a new and modern REST API web service.

The feature is currently in beta and is available to test from version 5.5.3.2 and up of Squiz Matrix. This document describes the current functionality as it stands today that you can use to test the feature.

This document is intended users who would like to test out the beta version of the API on a development environment and provide feedback on the feature for the Matrix development team to consider for the upcoming official release.

How to test

You need to do simple 2 things:

  1. Get a development environment of Squiz Matrix
  2. Enable the API

1. Development environment

First of all, you need to have access to a 5.5.3.2+ Matrix dev environment (or the head of the 5-5 branch).

The easiest way to do this is to download and spin up the public VM distribution of Squiz Matrix.

Alternatively, you could also download the core code (also found on the link mentioned above) and install Squiz Matrix on your own server.

2. Enabling the API

Once you have a development environment, you need to enable the API feature toggle (if not already enabled).

Do not enable this feature on a production system. The API is not production ready and enabling it could potentially expose sensitive data to the public.

To enable the API, locate this file in the Matrix server directory: data/private/conf/feature_flags.inc

Change the value of 'SQ_FEATURE_API_ENABLED' to true :

define('SQ_FEATURE_API_ENABLED', true);

Once that's done, you can connect to the API on any site domain using the /__api/ domain suffix, for example, https://www.example.com/__api/assets/{assetid} .

The API docs can be found under /__api/docs , for example, https://www.example.com/__api/docs .

Features

So far the API is very light. It's currently able to give you:

  • A single asset via ID or URL
  • The site lineage of an asset
  • The direct children of an asset

All data is returned as JSON.

Requests to the API are done via HTTP GET requests and by passing the Accept: application/json HTTP header.

For example:

curl --include \
     --header "Accept: application/json" \
     --request GET \
     https://www.example.com/__api/assets/{assetid}

Read the docs under /__api/docs to find out more about how to use these endpoints.

Authentication

Assets returned via the API are permission checked based on the Matrix session cookie.

If you want to return non-public assets, you need to pass this cookie as part of the request.

You don't have to though, and if you don't, the API will simply only return publicly accessible assets.

Providing feedback

We are super hungry for early developer feedback, so if you test it out and have any bugs, ideas, concerns, or questions to report you can send official product feedback using this form.

Alternatively you can also use this thread  in the Matrix forums to provide feedback, ideas, and early bugs.

Send Feedback

Noticed an error?
Want to suggest an improvement?

Let Us Know

The Latest

Let Us Know What You Think

Let us know if you spot any errors or if you have any ideas on how we can improve the Matrix Community Website.

Contact Squiz for Demo

Let us show you the true power of Squiz Matrix by giving you a personalised demonstration.