Data API Overview

The data branch (/data/{tenant}) is the primary API generated from the data model. It exposes every class as a REST resource — creating, reading, updating, deleting, querying, and exporting objects, plus file upload/download and a live event stream.

All paths in this branch are tenant-scoped: the first segment after /data is the tenant identifier.

/data/{tenant}/...

TypeFQN to URL mapping

Classes are identified in the model by their TypeFQN — namespace.name, for example commons.company. In the API, that identity is translated to URL segments by a fixed set of rules:

• The namespace is dropped. Only the name part appears in the URL; the namespace is implicit in the tenant context. commons.company and my-project.company both address a resource named company.
• Collections use the plural form. The plural is derived automatically from the singular name using English inflection rules (via the Evo inflector), so company → companies, person → people, agreement → agreements. You never write the plural in the model — it is always computed.
• The name is normalized to lower-first. EmploymentAgreement in the model is addressed as employmentAgreements in the URL.

Context	Form	Example
Collection (list, create)	plural	GET /data/{tenant}/companies
Single object	plural + id	GET /data/{tenant}/companies/{id}
Related sub-resource (multi-valued / inverse)	plural	GET /data/{tenant}/countries/{id}/companies
Single-valued relation field (inside object JSON)	singular	{ "country": "/data/{tenant}/countries/{id}" }

The internal type id is a deterministic UUID derived from the full namespace.name, so the same TypeFQN always maps to the same UUID — but that UUID does not appear in data URLs; the plural REST name does.

TODO

Confirm and document how a plural REST name is resolved back to a specific class when two namespaces define the same name (e.g. both commons.company and my-project.company). Explain the disambiguation rule (or that collisions are disallowed) and what happens on an unknown or ambiguous type name.

Endpoint map

The data branch is documented across the following pages. Every endpoint from the generated DataController is listed here; pages marked (stub) still need to be written.

Objects — Objects (stub)

Method	Path	Purpose
POST	{typeName}	Create an object.
POST	{referenceTypeName}/{referenceId}/{typeName}	Create an object related to an existing one.
GET	{typeName}/{id}	Get a single object.
GET	{typeName}/own	Get the caller's own object of this type.
PATCH	{typeName}/{id}	Partially update an object.
DELETE	{typeName}/{id}	Delete an object.

Querying — Querying objects (stub)

Method	Path	Purpose
GET	{typeName}	List/query objects of a type (filtered, paged, sorted).
GET	{relatedTypeName}/{relatedId}/{typeName}	List objects related to a given object.
GET	{typeName}/distinct	Distinct values for a field over a filtered set.
GET	{relatedTypeName}/{relatedId}/{typeName}/distinct	Distinct values within a related list.
GET	{typeName}/values/{fieldName}	Filtered values for a field of a type.

Aggregations — Aggregations ✅

Sum/avg/count over a filtered set. Standalone and related variants.

Global search — Global search ✅

Full-text search across a tenant.

Files — Files (stub)

Method	Path	Purpose
GET	upload	Obtain a signed upload URI.
GET	download/{id}	Obtain a signed download URI.

Exports — Reports & exports (stub)

Method	Path	Purpose
GET	{typeName}/{id}/reports/{reportName}	Generate a report document and get its URI.
GET	excel/{typeName}	Export a filtered list to Excel.
GET	excel/{relatedTypeName}/{relatedId}/{typeName}	Export a related list to Excel.

Operations & events — Operations (stub)

Method	Path	Purpose
POST	import	Import objects from an Excel file.
POST	loadDefaultData	Load the model's default data.
POST	rebuild	Rebuild the tenant's data.
POST	{typeName}/recalculate	Recalculate formulas for a type.
POST	{typeName}/sync	Sync a type.
DELETE	(root) ?name=&deleteTenant=	Delete tenant data (optionally the tenant).
GET	eventStream	Server-sent event stream of data changes.