Fields and field values
This page is for app developers who turn REST answers into the app's own data model. It explains the field routes, the shape of a field and, most important, how each value is written, so the app parses it correctly.
Contents
- The field routes
- The field object
- How values are written
- Mapping fields to your model
- When a field is not enough
The field routes
# every field of a node's object
curl -s -H "Authorization: Bearer $EXP_API_KEY" https://example.com/api/ezp/v2/content/node/<node id>/fields
# one field
curl -s -H "Authorization: Bearer $EXP_API_KEY" https://example.com/api/ezp/v2/content/object/<object id>/field/titleThe same fields come with ?ResponseGroups=Fields on a node, object or list read
(Response groups). The field routes default to the FieldValues group and add metadata only
with ?ResponseGroups=Metadata.
The field object
Each field, under its identifier in the fields map, has five keys (ezpRestContentModel::attributeOutputData()):
| Key | Meaning |
|---|---|
type | the datatype string, for example ezstring, ezxmltext, ezimage |
identifier | the field identifier of the class, for example title |
value | the value, see below |
id | the numeric id of this field of this object |
classattribute_id | the numeric id of the field definition in the class |
How values are written
| Datatype | value |
|---|---|
ezxmltext (rich text) | the field's rendered HTML with every tag removed: plain text, with no paragraphs, links or embedded images |
ezimage | the path of the original image file as stored by the image datatype (the part before | of its string form); the alternative text is cut off |
any datatype in site.ini [ContentSettings] DatatypeBlackListForExternal[] | null; the shipped list holds ezuser, so user accounts never leave through REST |
| every other datatype | the datatype's toString() representation |
The toString() form is the datatype's own simple export format. It differs per datatype (numbers, dates, booleans,
relation lists, selections), so test each datatype your classes use against a real answer before you write the
parser, and treat every value as a string that you convert. Do not guess formats from the field name.
Two consequences for apps:
- Rich text needs another source if the app shows formatting: Rich text in apps.
- Images need an alias URL for screen sizes: Images in REST answers.
Mapping fields to your model
- Key by
identifier, checktype. A class can change: an editor's administrator may add a field or change a datatype. Ignore unknown identifiers, and fail soft whentypeis not what the app expects. - Treat
nulland empty strings as "no value". Optional fields often come empty. - Keep
classIdentifierwith the item. It tells the app which screen or cell to use (Content classes for apps). - Do not depend on
id. A field'sidbelongs to one object; it is not useful as a key across items. Useclassattribute_idoridentifierfor the field definition.
When a field is not enough
| Need | Source |
|---|---|
| A field in another language | ?Translation=<locale> (Multilingual content) |
| Attribute values as the remote services export them | expnode::dataMap::<node id> or expnode::attribute::<node id>::<identifier> (Calling expservices from an app) |
| A computed or combined value | a server function written for the app (ezjscore server functions for your app) |
Related pages
- Reading a node
- Choosing datatypes
- How Exponential content reaches an app
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.