Layout API

The FLOW Layout API provides is for controlling the section/topic/author/etc pages

The layout entities link to a publication and taxonomy term like a section or a topic

The taxonomy terms do not know about the layout entities that link to them

There is a JSON field on these entities and the CMS creates an array of component objects that the API then uses to build the response for the section pages

Endpoints

// New endpoints
/api/layout/bundles
/api/layout/search/{publicationDomain}

// Old Endpoints
/api/components/{componentType}
/api/layout/default
/api/layout/{componentType}/{publicationDomain}
/api/layout-lists/{id}
/api/layout-update/{id}

Bundles

The bundles endpoint provides the CMS with a list of available bundles for the layout entities

Example call

https://indy-api-dev.brightsites.co.uk/api/layout/bundles

Search

The search endpoint provides a way to search layout entities, there are filters for bundle and a search q

It has 2 formats, the first is the default and does not include the layout settings json object, if you want the layout settings to be included in the response then add &format=full to the query

It also has limit and offset for paging and it is ordered by updated date with the option to reverse it sort=asc or desc is default if omitted.

Example calls

// All layout entities for the publication
https://indy-api-dev.brightsites.co.uk/api/layout/search/independent.co.uk

// All layouts filtered by bundle
https://indy-api-dev.brightsites.co.uk/api/layout/search/independent.co.uk?bundle=section_layout

// All layouts filtered by bundle with a search query
https://indy-api-dev.brightsites.co.uk/api/layout/search/independent.co.uk?bundle=section_layout&q=news

// All layouts filtered by bundle with a search query with the layout settings included
https://indy-api-dev.brightsites.co.uk/api/layout/search/independent.co.uk?bundle=section_layout&q=news&format=full

// Paging
https://indy-api-dev.brightsites.co.uk/api/layout/search/independent.co.uk?limit=10&offset=20

// Sorting
https://indy-api-dev.brightsites.co.uk/api/layout/search/independent.co.uk?sort=asc
https://indy-api-dev.brightsites.co.uk/api/layout/search/independent.co.uk?sort=desc

// Default is same as &sort=desc
https://indy-api-dev.brightsites.co.uk/api/layout/search/independent.co.uk

Components

The components endpoint provides the list of section and sidebar components to the CMS

It is filterable by publication and is only available to logged-in users

Example calls

// All components
https://indy-api-dev.brightsites.co.uk/api/components/section
https://indy-api-dev.brightsites.co.uk/api/components/sidebar

// All components available for The Independent
https://indy-api-dev.brightsites.co.uk/api/components/section?domain=independent.co.uk
https://indy-api-dev.brightsites.co.uk/api/components/sidebar?domain=independent.co.uk

// Another list of the components
https://indy-api-dev.brightsites.co.uk/api/layout/default
https://indy-api-dev.brightsites.co.uk/api/layout/default?domain=independent.co.uk

Layout Entities

The layout entities have the following bundles, although we do not use them all

article_type
author
chain
event
people
section
sidebar
tag
team
topic

You can then use these bundles to search the layouts

eg:

// All Layouts from the `section` bundle
https://indy-api-dev.brightsites.co.uk/api/layout/section/independent.co.uk

// Search for section layout entities by the path of a term
https://indy-api-dev.brightsites.co.uk/api/layout/section/independent.co.uk?path=/sport

Manual Lists in Layouts

Get all manual lists for a layout by layout id

https://indy-api-dev.brightsites.co.uk/api/layout-lists/123

Updating Layouts and their Manual Lists

The Layout update controller is a custom endpoint as we process the manual lists at the same time as saving the Layout entity

It accepts a JSON object payload in the same way the REST API does but you can also add an array of manual lists to process at the same time manual_lists

manual_lists is optional as not all layouts will use manual lists

https://indy-api-dev.brightsites.co.uk/api/layout-update/123

There is also a field that is used to stop 2 people editing the same layout at the same time called client_changed_time

The API validates that the time in their browser matches the time in the entity before allowing it to save

The endpoint returns the REST API formatted JSON of the entity for the CMS to use