Create a page using the asset management API

REST API

The asset management API is a Representational State Transfer (REST) API. This means that it complies with the REST architectural constraints.

Why build a page using APIs?

There are many use cases for using an API to build a Matrix page. The most common use case is when you need to create many pages at one time, for example:

  • A university needs to create new pages twice a year to show which courses are available and provide details

  • A retail business needs to create pages automatically from their product database.

  • A multi-lingual website wants to automatically create translated copies of pages when a page is updated.

  • A council wants to automatically publish a list of services from its database to its website.

Instead of using the Matrix UI to create each page individually you can write code to create many pages quickly.

Before you start

There are some setup steps before using the Squiz Matrix asset management API.

  1. Get an API token. Read Tokens to find out how to get an API token.

  2. Authentication:: Each request needs to be authenticated with a bearer token. Read Authentication for information about the bearer token.

Steps to create a standard page asset

The asset management API manipulates individual Matrix assets. Standard pages are compound assets made up of multiple dependent assets, so there are four steps to creating a page through the API:

Each step is dependent on the successful completion of the previous step.

Asset structure

These instructions will create a structure like the one shown in the following image:

asset management api file structure

The structure supports the dependent nature of the assets.

Error Responses

Read Error responses for explanations of the most common error codes.

Open API definition

Read Open API details for more information about the API definition.

Create a standard page asset

This section shows you how to use the API to create a new standard page asset from within your code.

Command

Use the following command to create your standard page asset:

POST https://website.matrix.squiz.cloud/__management_api/v1/assets

Payload

Set the following fields as shown on the example standard page payload:

{
    "asset": {
        "type": "page_standard",         (1)
        "attributes": {
            "name": "EXAMPLE PAGE",      (2)
            "short_name": "Example Page"
        },
        "published": null,
        "metadata_schemas": [],
        "metadata_values": null
    },
    "parent": {
        "asset_id": "1",                (3)
        "link_type": "menu",
        "value": "",
        "sort_order": -1,
        "is_dependent": false,
        "is_exclusive": false
    }
}
1 Set the type to page_standard
2 Give the asset a name in the name field
3 Specify where to place the new field by adding the parent asset ID in the parent:asset_id field.

Response

Newly created assets will have a Matrix status of under_construction

The API response will contain:

{
    "id": "1821",                  (1)
    "type": "page_standard",       (2)
    "attributes": {
        "name": "EXAMPLE PAGE",    (3)
        "short_name": "Example Page"
    },
    "status": "under_construction",
    "version": "0.0.1",
    "created": {
        "date_time_unix": 1641875024,
        "user_id": "1227"
    },
    "updated": {
        "date_time_unix": 1641875025,
        "user_id": "1227"
    },
    "published": null,
    "status_changed": {
        "date_time_unix": 1641875024,
        "user_id": "1227"
    },
    "metadata_schemas": [],
    "metadata_values": null,
    "paint_layouts": {
        "asset_level": null,
        "asset_level_override": null,
        "url_based": {},
        "user_defined": {}
    }
}
1 The asset ID in the id field
2 The asset type created in the type field
3 The name spefied in the payload.

Create a bodycopy asset

After you have created a new standard page, you must add a bodycopy asset as a child of the standard page. Bodycopy assets usually appear with the name Page Contents under standard pages in the asset tree.

Command

Use the following command to create a bodycopy asset:

POST https://website.matrix.squiz.cloud/__management_api/v1/assets

Payload

Set the following fields as shown on the example bodycopy asset payload:

"asset": {
        "type": "bodycopy",            (1)
        "attributes": {
            "name": "Page Contents"    (2)
        },
        "published": null,
        "metadata_schemas": [],
        "metadata_values": null
    },
    "parent": {
        "asset_id": "1821",            (3)
        "link_type": "hidden",
        "value": "",
        "sort_order": -1,
        "is_dependent": true,
        "is_exclusive": true
    }
}
1 Set the type field to bodycopy
2 Add a descriptive name to the name field
3 Set the parent:asset_id to the value of the id field in the response of your newly created page asset.

Response

The API response will contain:

{
    "id": "1822",                   (1)
    "type": "bodycopy",             (2)
    "attributes": {
        "name": "Page Contents"     (3)
    },
    "status": "under_construction",
    "version": "0.0.1",
    "created": {
        "date_time_unix": 1643676269,
        "user_id": "1227"
    },
    "updated": {
        "date_time_unix": 1643676270,
        "user_id": "1227"
    },
    "published": null,
    "status_changed": {
        "date_time_unix": 1643676269,
        "user_id": "1227"
    },
    "metadata_schemas": [],
    "metadata_values": null,
    "paint_layouts": {
        "asset_level": null,
        "asset_level_override": null,
        "url_based": {},
        "user_defined": {}
    },
    "web_paths": null
}
1 The asset ID in the id field
2 The asset type created in the type field
3 The name specified in the payload.

Create a component asset

Add a component asset as a child of your bodycopy asset.

NOTE:The content component asset is referred to as a bodycopy_div asset type.

Command

Use the following command to create a component asset:

POST https://website.matrix.squiz.cloud/__management_api/v1/assets

Payload

Each component asset has a child asset - the component content asset. The content_type field on the component asset must match the type field on the component content asset. You can choose either a WYSIWYG or Raw HTML type, which will determine the editing experience for the component in the Matrix admin UI. In the example in this guide, the content_type and type fields are both set to content_type_wysiwyg.

For reference, the raw HTML setting value is content_type_raw_HTML.

Set the following fields as shown on the example component asset payload:

{
    "asset": {
        "type": "bodycopy_div",                           (1)
        "attributes": {
            "name": "Component",                          (2)
            "description": "",
            "attributes": {
                "content_type": "content_type_wysiwyg",   (3)
                "layout_type": "div",
                "container_id": "",
                "template": "",
                "css_class": "",
                "dir": "ltr",
                "disable_keywords": false,
                "use_custom_id": false
            },
            "template_applied": false,
            "comments": "",
            "persona_evaluation": "any"
        },
        "published": null,
        "metadata_schemas": [],
        "metadata_values": null
    },
    "parent": {
        "asset_id": "1822",                               (4)
        "link_type": "hidden",
        "value": "",
        "sort_order": -1,
        "is_dependent": true,
        "is_exclusive": false
    }
}
1 Set the type field to bodycopy_div
2 Add a descriptive name to the name field
3 Set content_type field to content_type_wysiwyg
4 Set the parent:asset_id to the value of the id field in the response of the bodycopy asset created in the previous step.

Response

The API response will contain:

{
    "id": "1823",                       (1)
    "type": "bodycopy_div",             (2)
    "attributes": {
        "name": "Component",            (3)
        "description": "",
        "attributes": {
            "content_type": "content_type_wysiwyg",
            "layout_type": "div",
            "container_id": "",
            "template": "",
            "css_class": "",
            "dir": "ltr",
            "disable_keywords": false,
            "use_custom_id": false
        },
        "template_applied": false,
        "comments": "",
        "persona_evaluation": "any"
    },
    "status": "under_construction",
    "version": "0.0.1",
    "created": {
        "date_time_unix": 1643765207,
        "user_id": "1227"
    },
    "updated": {
        "date_time_unix": 1643765207,
        "user_id": "1227"
    },
    "published": null,
    "status_changed": {
        "date_time_unix": 1643765207,
        "user_id": "1227"
    },
    "metadata_schemas": [],
    "metadata_values": null,
    "paint_layouts": {
        "asset_level": null,
        "asset_level_override": null,
        "url_based": {},
        "user_defined": {}
    },
    "web_paths": null
}
1 The asset ID in the id field
2 The asset type created in the type field
3 The name spefified in the payload.

Create a component content asset

Create a component content asset as a child of the component asset.

The component content asset stores the HTML contents of your page components. The type field must contain the same value as the content_type field in the parent component asset created in the last step.

Command

Use the following command to create a component asset:

POST https://website.matrix.squiz.cloud/__management_api/v1/assets

Payload

Set the following fields as shown on the example component content payload:

{
    "asset": {
        "type": "content_type_wysiwyg",  (1)
        "attributes": {
            "name": "Component Content", (2)
            "html": "<p>This is example content for the example page.</p>"
        }
    },
    "parent": {
        "asset_id": "1823",              (3)
        "link_type": "hidden",
        "value": "div_contents",
        "sort_order": 0,
        "is_dependent": true,
        "is_exclusive": true
    }
}
1 Set the type field to content_type_wysiwyg
2 Add a descriptive name to the name field
3 Set the parent:asset_id to the value of the id field in the response of the component asset created in the previous step.

Response

The API response will contain:

{
    "id": "1824",                     (1)
    "type": "content_type_wysiwyg",   (2)
    "attributes": {
        "name": "Component Content",  (3)
        "html": "<p>This is example content for the example page.</p>",
        "htmltidy_status": "wait",
        "htmltidy_errors": "No error found"
    },
    "status": "under_construction",
    "version": "0.0.1",
    "created": {
        "date_time_unix": 1643868373,
        "user_id": "1227"
    },
    "updated": {
        "date_time_unix": 1643868374,
        "user_id": "1227"
    },
    "published": null,
    "status_changed": {
        "date_time_unix": 1643868373,
        "user_id": "1227"
    },
    "metadata_schemas": [],
    "metadata_values": null,
    "paint_layouts": {
        "asset_level": null,
        "asset_level_override": null,
        "url_based": {},
        "user_defined": {}
    },
    "web_paths": null,
    "urls": []
}
1 The asset ID in the id field
2 The asset type created in the type field
3 The name specified in the payload.

Result

When you run the instructions above in order, you will end up with the structure shown in Asset structure:

asset management api file structure

You will need to run the whole set of four asset creation steps in this guide for each page required.