REST API & Data Integration

Struktural automatically generates a comprehensive, secure REST API for every persistent and virtual entity defined in your schema. This allows external systems, custom frontends, and integration middleware (like Zapier or MuleSoft) to interact with your data programmatically.

Base URL & Authentication

All dynamic entity endpoints follow the tenant-based routing structure:

https://{your-server}/api/apps/{appId}/{EntityName}

• appId: The tenant identifier (e.g., erp-client-a). If omitted (or if querying /api/{EntityName}), the engine assumes the default application.
• EntityName: The strict PascalCase name of the entity (e.g., SalesOrder).

Authentication & Authorization: Requests MUST include a valid authentication token (either an Authorization: Bearer <JWT> header or an ASP.NET Auth Cookie). The authenticated user must have the corresponding RBAC permission (Create, Read, Update, Delete) granted for the target entity.

1. Standard CRUD Operations

Get by ID

• Endpoint: GET /{id}
• Description: Retrieves a single record by its numeric ID.
• Response: Returns a standard Result<T> JSON wrapper containing the entity data, automatically omitting fields the user is restricted from viewing via Field-Level Security (FLS).

Create Record

• Endpoint: POST /
• Description: Creates a new record. Triggers the BeforeCreate and AfterCreate C# lifecycle scripts.
• Payload: The raw JSON object matching the Entity schema. Do not include the Id field.
• Response: Returns the created entity (with its new ID) inside the Value property of the Result wrapper.

Update Record

• Endpoint: PUT /{id}
• Description: Completely updates a record. Triggers the BeforeUpdate and AfterUpdate scripts.
• Payload: The raw JSON object.
• Security Note: Any fields excluded from the payload, or fields the user does not have permission to write to, will retain their original database values.

Delete Record

• Endpoint: DELETE /{id}
• Description: Deletes a record. If the entity is marked as IsAudited: true, this performs a Soft Delete and records the deletion in the audit trail.

2. Advanced Query & Pagination

Instead of relying on complex URL query strings, Struktural provides a powerful POST endpoint for searching, sorting, and filtering data.

• Endpoint: POST /query
• Description: Returns a paginated list of records matching the criteria.

Payload Schema (EntityQueryRequest)

{
  "Page": 1,
  "PageSize": 50,
  "SortBy": "CreatedAt",
  "SortDirection": "desc",
  "SearchTerm": "John",
  "Includes": ["Customer", "OrderLines"],
  "Filter": {
    "Logic": "AND",
    "Children": [
      { "Field": "Status", "Operator": "eq", "Value": "Active" },
      { "Field": "TotalAmount", "Operator": "gte", "Value": 1000 }
    ]
  }
}

• SearchTerm: Performs a "Contains" search across the fields designated in the entity's DisplayFormat.
• Includes: An array of navigation property names to eager-load (SQL JOIN) alongside the base entity.
• Filter: A recursive FilterNode object. For full syntax and dynamic date mathematics, refer to the Filtering Syntax Reference.

Response Schema (PagedResult<T>)

{
  "Success": true,
  "Value": {
    "Items": [ { "Id": 1, "Status": "Active", "TotalAmount": 1500 } ],
    "TotalCount": 1,
    "Page": 1,
    "PageSize": 50,
    "TotalPages": 1
  },
  "ErrorMessage": null,
  "ValidationErrors": [],
  "FieldErrors": {}
}

3. Standard API Error Handling

If a request fails validation (either static schema constraints or custom AddError() calls from a C# script), the API returns a 400 Bad Request with the following populated Result structure:

{
  "Success": false,
  "ErrorMessage": "Validation failed during script execution.",
  "ValidationErrors": [
    "The provided email is already in use."
  ],
  "FieldErrors": {
    "TotalAmount": [
      "Must be greater than 0"
    ]
  }
}

4. Bulk Data Import API

Struktural provides a native endpoint to upload and map external Excel (.xlsx) or CSV files directly into an entity. This process wraps all row insertions into a single database transaction and executes the BeforeImport and AfterImport scripts.

• Endpoint: POST /import/execute
• Content-Type: multipart/form-data

Form-Data Fields

1. file: The physical file binary.
2. mappingJson: A JSON string representing the ImportMappingRequest object, which tells the engine how to map file columns to entity properties.

mappingJson Structure

{
  "EntityName": "Employee",
  "SheetName": "Sheet1",
  "HeaderRow": 1,
  "FieldMappings": {
    "Excel Column A": "FirstName",
    "Excel Column B": "LastName",
    "Hire Date": "StartDate"
  }
}

• HeaderRow: The 1-based index of the row containing the column headers in the spreadsheet.
• FieldMappings: A dictionary where the Key is the exact string found in the file's header row, and the Value is the physical Property Name on the target Struktural Entity.