Entity Structure

An entity represents a data model or table within the system, encapsulating its structure, fields, and relationships with other entities. Entities are fundamental data structures in the application, which are allowed to save, retrieve, and manipulate data records.

Properties of an Entity

To create an entity from scratch, it’s needed to define its properties, fields, and relationships. Below are the key properties of an entity:

Field	Type	Description
audited	boolean	Indicates if changes to the entity’s records should be logged for auditing purposes.
read_only	boolean	When true, prevents any modification to the entity’s records through entire system.
importable	boolean	Indicates whether records for this entity can be imported from an external source.
show_on_menu	boolean	Determines if this entity will appear as an item in the main navigation menu.
schema	string	Database schema where the entity’s table is located. (internal entities will use public)
datasource	string	Identifier for the database connection that this entity should use.
object_name	string	Internal, technical name of the entity object, often corresponding to the database table name.
object_label	string	Human-readable name for the entity, used for display purposes in the user interface.
fields	Array<Field>	Array of objects that define the attributes of the entity.
list_as	Array<string>	Array of field names to be displayed by default in list views for this entity.
relationships	Array<Relationship>	Array of objects, each defining a relationship (e.g., many-to-one) with another entity.

Entity endpoint payload example

While working with API calls, it is essential to understand the structure of the payload when creating or updating an entity. Below is an example of a JSON payload for an entity:

{
  "audited": true,
  "read_only": false,
  "importable": true,
  "show_on_menu": true,
  "schema": "dasec",
  "datasource": "",
  "object_name": "entity",
  "object_label": "Entity",
  "fields": [],
  "list_as": [],
  "relationships": []
}

Properties of a Field

Field	Type	Default Value	Required	Description
len	number	0	Yes	Length of the field (for strings, etc).
size	number	0	Yes	Size of the field (for numeric, etc).
precision	number	0	Yes	Precision for decimal fields.
comments	string	""	No	Comments or notes about the field.
group	string	""	No	Group to which the field belongs.
help	string	""	No	Help text for the field.
label	string		Yes	Label for display purposes.
name	string		Yes	Internal name of the field.
schema	string	public	No	Unused, defaults to public, do not modify.
type	string	integer	Yes	Data type of the field.
regex	string	""	No	Regular expression for validation.
default_exp	string	""	No	Default value expression.
options_exp	string	""	No	Expression to generate options.
audited	boolean	true	No	Indicates if changes to the field are audited.
importable	boolean	false	No	Indicates if the field can be imported.
reportable	boolean	false	No	Indicates if the field is reportable.
visible	boolean	true	No	Determines if the field is visible in the UI.
auto_increment	boolean	false	No	If true, the field auto-increments.
default_value	any	null	No	Default value for the field.
editable	boolean	true	No	If true, the field is editable.
indexable	boolean	true	No	If true, the field is indexable.
inline_edit	boolean	false	No	If true, the field can be edited inline.
readonly	boolean	false	No	If true, the field is read-only.
required	boolean	true	No	If true, the field is required.
searchable	boolean	true	No	If true, the field is searchable.
unique	boolean	false	No	If true, the field must be unique.
options	Array<Option>	[]	No	List of options for select fields.

Supported field types

The following field types are supported:

Type	Value (key)	Description
Date and time	datetime	Date and time value
Date	date	Date value
Time	time	Time value
Text	text	Long text
String	string	Short text or string
Option	option	Selectable option
Number	number	Numeric value
Decimal	decimal	Decimal number
Integer	integer	Integer number
Array	array	Array of values
Boolean	boolean	True/false value
File	file	File upload
Image	image	Image upload

Field endpoint payload example

{
  "len": 0,
  "size": 0,
  "precision": 0,

  "comments": "",
  "group": "",
  "help": "",
  "label": "Field",
  "name": "field",
  "schema": "public",
  "type": "integer",

  "regex": "",
  "options": [],
  "default_exp": "",
  "options_exp": "",

  "audited": true,
  "importable": false,
  "reportable": false,
  "visible": true,

  "auto_increment": false,
  "default_value": null,
  "editable": true,
  "indexable": true,
  "inline_edit": false,
  "readonly": false,
  "required": true,
  "searchable": true,
  "unique": true
}

Properties of a Relationship

Field	Type	Default Value	Required	Description
relation_name	string		Yes	Internal name of the relationship.
name	string		Yes	Same as relation_name, for compatibility.
label	string		Yes	Human-readable label for the relationship.
relationship_type	string		Yes	Type of relationship the entity has with another. (type)
type	string		Yes	one-to-one, many-to-one, one-to-many, many-to-many.
l_entity	string		Yes	Left entity ID
l_key	string		Yes	The column in the left entity of the relationship.
r_entity	string		Yes	Right entity ID
r_key	string		Yes	Key in the right entity.
dependency	string	""	No	If this relationship depends on a third entity, set.
dependency_relation	string	""	No	Relationship it depends on third entity, if any.

Relationship endpoint payload example

{
  "relation_name": "RS_00000000-0000-0000-AAAA-0123456789AB.right_id_00000000-0000-0000-BBBB-0123456789AB.id",
  "name": "RS_00000000-0000-0000-AAAA-0123456789AB.right_id_00000000-0000-0000-BBBB-0123456789AB.id",

  "label": "menu_has_category_menu -> menu",

  "relationship_type": "many-to-one",
  "type": "many-to-one",

  "l_entity": "00000000-0000-0000-AAAA-0123456789AB",
  "l_key": "right_id",

  "r_entity": "00000000-0000-0000-BBBB-0123456789AB",
  "r_key": "id",

  "dependency": "",
  "dependency_relation": ""
}

Endpoints for managing entities

Create a new entity

Create a new entity. Stored to be manipulated in the Studio.

Endpoint:

POST /api/v1/entities?version=:version

<Entity>

Response Example:

{
  "status": 201,
  "error": false,
  "message": "string",
  "entityName": "string",
  "data": [ { <Entity> } ]
}

Update an entity

Update an existing entity. Stored to be manipulated in the Studio.

Endpoint:

PUT /api/v1/entities/:entity?version=:version

Request Example:

{
  "audited": true,
  "importable": true,
  "readOnly": false,
  "showOnMenu": true,
  "datasource": "",
  "listAs": []
}

Response Example:

{
  "status": 200,
  "error": false,
  "message": "string",
  "entityName": "string",
  "data": [ { <Entity> } ]
}

Delete an entity

Delete an existing entity.

Endpoint:

DELETE /api/v1/entities/:entity?version=:version

Response Example:

{
  "status": 200,
  "error": false,
  "message": "string",
  "entityName": "string"
}

Endpoints for managing fields

Get entity fields

Returns the entity fields.

Endpoint:

GET /api/v1/entities/:entity/fields?page=:page&limit=:limit?&version=:version

Response Example:

{
  "status": 200,
  "error": false,
  "message": "string",
  "entityName": "string",
  "data": [ { <Field> } ],
  "pagination": { <Pagination> }
}

Add a field to an entity

Add a field in the JSON entity field.

Endpoint:

POST /api/v1/entities/:entity/fields?version=:version

<Field>

Response Example:

{
  "status": 201,
  "error": false,
  "message": "string",
  "entityName": "string",
  "data": [ { <Field> } ]
}

Update a field

Updates a field in the JSON entity field.

Endpoint:

PUT /api/v1/entities/:entity/fields/:field?version=:version

<Field>

Response Example:

{
  "status": 200,
  "error": false,
  "message": "string",
  "entityName": "string",
  "data": [ { <Field> } ]
}

Delete a field

Deletes a field in the JSON entity field.

Endpoint:

DELETE /api/v1/entities/:entity/fields/:field?version=:version

Response Example:

{
  "status": 200,
  "error": false,
  "message": "string",
  "entityName": "string"
}

Endpoints for managing relationships

Returns the entity relationships.

Get entity relationships

Endpoint:

GET /api/v1/entities/:entity/relationships?page=:page&limit=:limit&direct=:direct&version=:version

Response Example:

{
  "status": 200,
  "error": false,
  "message": "string",
  "entityName": "string",
  "data": [ { <Relationship> } ],
  "pagination": { <Pagination> }
}

Create a relationship

Creates a relationship in the JSON entity file and its data in the database.

Endpoint:

POST /api/v1/entities/relationships?version=:version

<Relationship>

Response Example:

{
  "status": 201,
  "error": false,
  "message": "string",
  "entityName": "string",
  "data": [ { <Relationship> } ]
}

Update a relationship

Updates a relationship in the JSON entity file and its data in the database.

Endpoint:

PUT /api/v1/entities/:entity/relationships/:relationship?version=:version

<Relationship>

Response Example:

{
  "status": 200,
  "error": false,
  "message": "string",
  "entityName": "string",
  "data": [ { <Relationship> } ],
  "pagination": { <Pagination> }
}

Delete a relationship

Deletes a relationship in the JSON entity file and its data in the database.

Endpoint:

DELETE /api/v1/entities/:entity/relationships/:relationship?version=:version

Response Example:

{
  "status": 200,
  "error": false,
  "message": "string",
  "entityName": "string"
}

Other endpoints

Get an entity attribute or settings

Get an entity attribute or settings.

Endpoint:

GET /api/v1/entities/:entity/:attribute

Response Code:

• 200: OK