Use Metadata API in UI

After this page, you can load source metadata from the API and render basic filter/sort field controls in your frontend.

How the architecture works

flowchart LR
    Developer["Developer (registers trusted sources)"] --> AppBoot["LaravelAppBoot"]
    AppBoot --> Registry["DataSourceRegistry"]
    Registry --> ReportBuilder["ReportBuilderService"]
    Frontend["FrontendBuilderUI"] -->|"GET /report-builder/sources"| DataSourceController["DataSourceController"]
    Frontend -->|"GET /report-builder/sources/{source}"| DataSourceController
    DataSourceController --> ReportBuilder
    ReportBuilder --> Registry
    Registry --> DataSource["EloquentDataSource"]
    DataSource --> FieldDefinitions["FieldDefinitions (safe metadata only)"]
    FieldDefinitions --> ApiResponse["JSONMetadataResponse"]
    ApiResponse --> Frontend

This flow shows the trust boundary: frontend only receives safe metadata, while trusted source definitions remain in backend code.

Step 1: Fetch available sources

const sourcesResponse = await fetch('/report-builder/sources');
const sourcesPayload = await sourcesResponse.json();
const sources = sourcesPayload.data;

Each source has:

• key
• label

Step 2: Fetch one source detail

const detailResponse = await fetch('/report-builder/sources/orders');
const detailPayload = await detailResponse.json();
const fields = detailPayload.data.fields;

Each field has:

• key
• label
• type
• sortable
• groupable
• filter_operators
• aggregate_functions
• format

Step 3: Build controls from metadata

Use filter_operators to render only valid operators per selected field.

Use sortable and groupable flags to enable or disable controls.

Verify

• Field dropdown shows only API fields.
• Operator dropdown changes based on selected field.
• UI does not hardcode operators globally.

Common mistakes

• Hardcoding field names in UI.
• Ignoring per-field operator restrictions.
• Assuming every field is sortable.

Next

Use task guides in How-to for production patterns.