Six block types, on one page
A page is a list of blocks and nothing else. Learn the six and you have learnt the whole data model.
The six
Every block is an object with a type and that type’s fields. Over the agent endpoints the id, the order and the visibility flag are optional: the server assigns an id, keeps the order you sent, and shows the block. Send them back only when you have read a page and are editing it in place.
| Type | Needs | May also have |
|---|---|---|
| link | label, url | note, image, badge, featured, adult, path, apps, imageFocus |
| socialRow | items of platform and url | up to twenty items |
| social | platform, url | counter |
| messenger | platform, handle | label |
| embed | provider, url | title |
| text | content | variant of heading or paragraph |
A url may be http or https, or a phone number as tel with a country code, or an address as mailto. A bare hostname is accepted too and stored with https. Images are storage keys from the upload route, never addresses. Every block may carry a start and an end moment, outside which it is not rendered.
The constraints no schema can express
- Short paths are unique within a page: two links cannot both be «shop», and a collision comes back as an error naming the path.
- Service words — api, go, gate, media — cannot be short paths.
- Eighty blocks per page is the ceiling, and any page approaching it is already too long to read.
- Sending blocks in an update replaces the whole list; there is no partial merge, because merging two block lists has no sensible definition.
A shape that usually works
One featured link for the thing that matters this month, two to five plain links after it in order of importance, one social row with every platform, a messenger or phone button if enquiries arrive that way, and a text heading only if the page is long enough to need dividing.
That is five to nine blocks. It fits on a phone screen and a half, it reads in one pass, and it is what the recipes in the documentation produce for a musician, a restaurant, a photographer or a shop — with the nouns changed and nothing else.