Skip to Content
FrontendAppsReportAPI Calls Documentation

API Calls Documentation

Table of Contents

  1. Introduction
  2. External API Endpoints
  3. Internal API Routes

Introduction

An overview of the API calls that we make in the report app and their purpose.

This report application renders dashboard reports and widgets, runs data collectors/processors, and persists per-user listing/filter preferences. All backend calls go to the tenant’s PHPR API and carry the JWT from the currentUser cookie as a Bearer token.

External API Endpoints

PHPR Backend (tenant API)

All PHPR endpoints are tenant-based and constructed dynamically. Two helpers build the URL and send the request:

  • buildPhprUrl(tenant, env, version, resource) from frontend-utils (used by src/utils/functions/serverApi.ts)

  • callPhprApi(method, tenant, resource, body?) from frontend-utils (used by widgetApi.ts and data-collector/actions.ts)

  • Base URL: https://{tenant}{NEXT_PUBLIC_API_PHPR_ENV}.phpr.link/{API_ENDPOINT_VERSION}/

  • Default version: open-api/v3

  • Auth header: Authorization: Bearer {currentUser JWT}

  • Locale header: Accept-Language: {locale}_CA

dashboard_reports/{id}

  • Description: Fetch a report by numeric id, or by slug via ?slug={slug} (returns first hydra:member).
  • Method: GET
  • Used in: src/utils/functions/serverApi.ts — fetchReport()

dashboard_reports/{id}/complete

  • Description: Fetch a complete report including all relations.
  • Method: GET
  • Used in: It’s not used.

dashboard_reports/{id}/export/complete

  • Description: Export the complete report, including all relations, into a JSON file.
  • Method: GET
  • Used in: It’s not used.

dashboard_reports/import/complete

  • Description: Import the complete report, including all relations, from a JSON file.
  • Method: POST
  • Used in: It’s not used.

dashboard_widgets/{id}

  • Description: Fetch a widget by numeric id, or by slug via ?slug={slug}.
  • Method: GET
  • Used in: src/utils/functions/serverApi.ts — fetchWidget()

dashboard_widgets/{id}/metadata

  • Description: Widget metadata (parameters, result columns) used to build the populate query.
  • Method: GET
  • Used in: src/utils/functions/widgetApi.ts — fetchWidgetMetadata() / fetchWidgetRenderData()

dashboard_widgets/{id}/populate

  • Description: Widget data rows. Called with a query string of parameter values (?key=value&...&search=...).
  • Method: GET
  • Used in: src/utils/functions/widgetApi.ts — fetchWidgetPopulate() / fetchWidgetPopulateList()

dashboard_reportwidgets?report={id} | ?widget={id}

  • Description: Report↔widget link records; resolves linked reports/widgets.
  • Method: GET
  • Used in: src/utils/functions/serverApi.ts — fetchReportWidgetLinked()

templates/{id}

  • Description: Fetch a template by identifier.
  • Method: GET
  • Used in: src/utils/functions/serverApi.ts — fetchTemplate()

templates?name={name}

  • Description: Look up a template source by name (returns first member with a non-empty source).
  • Method: GET
  • Used in: src/utils/functions/serverApi.ts — fetchTemplateSourceByName()

fee_currencies

  • Description: Currency definitions (code, symbol, decimal separator, digits) used for column formatting.
  • Method: GET
  • Used in: src/utils/functions/serverApi.ts — fetchCurrencies()

dataanalysis_datacollectors/{id}

  • Description: Fetch a data collector by numeric id, or by slug via ?slug={slug}.
  • Method: GET
  • Used in:
    • src/utils/functions/serverApi.ts — fetchDataCollector()
    • src/app/[locale]/data-collector/actions.ts — getDataCollector()

dataanalysis_datacollectors/{id}/execute

  • Description: Execute a data collector; optional query string of parameter values.
  • Method: GET
  • Used in:
    • src/utils/functions/serverApi.ts — fetchDataCollectorExecute()
    • src/app/[locale]/data-collector/actions.ts — getDataCollectorExecute()

dataanalysis_datacollectors/{id}/get_query

  • Description: Return the underlying query for a data collector.
  • Method: GET
  • Used in: src/app/[locale]/data-collector/actions.ts — getDataCollectorQuery()

dataanalysis_datacollectors/{id}/generate/results

  • Description: Generate DataCollectorResult entities for the given DataCollector based on the directives.
  • Method: POST
  • Used in: It’s not used.

dataanalysis_datacollectors/{id}/generate/parameters

  • Description: Generate DataCollectorParameter entities for the given DataCollector based on the directives.
  • Method: POST
  • Used in: It’s not used.

dataanalysis_datacollectors/{id}/generate/filters

  • Description: Generate Dashboard Filter entities for the given DataCollector based on the existing collector’s parameters.
  • Method: POST
  • Used in: It’s not used.

dataanalysis_datacollectors/{id}/generate/data_processor

  • Description: Generate a DataProcessor based on the DataCollector. Also generates the DataProcessorResult entities based on the DataCollector’s results.
  • Method: POST
  • Used in: It’s not used.

dataanalysis_datacollectors/{id}/generate/widget/listing

  • Description: Generate a default listing widget with all relations (DataProcessor, processor results, widget, template) based on the DataCollector.
  • Method: POST
  • Used in: It’s not used.

dataanalysis_datacollectors/{id}/generate/widget/summary

  • Description: Generate a default summary widget with all relations (DataProcessor, processor results, widget, template) based on the DataCollector.
  • Method: POST
  • Used in: It’s not used.

dataanalysis_datacollectors/{id}/generate/widget/graph

  • Description: Generate a default line graph widget with all relations (DataProcessor, processor results, widget, template) based on the DataCollector.
  • Method: POST
  • Used in: It’s not used.

dataanalysis_datacollectorparameters?dataCollector={id}

  • Description: Parameters defined for a data collector.
  • Method: GET
  • Used in:
    • src/utils/functions/serverApi.ts — fetchDataCollectorParameters()
    • src/app/[locale]/data-collector/actions.ts — getDataCollectorParameters()

dataanalysis_dataprocessors/{id}

  • Description: Fetch a data processor by numeric id or slug.
  • Method: GET
  • Used in: src/utils/functions/serverApi.ts — fetchDataProcessor()

dataanalysis_dataprocessors

  • Description: Create a data processor.
  • Method: POST
  • Used in: src/utils/functions/serverApi.ts — createDataProcessor()
  • Request Body: 
    { "title": "string", "slug": "string" }

dataanalysis_dataprocessors/{id}/metadata

  • Description: Data processor metadata.
  • Method: GET
  • Used in: src/utils/functions/serverApi.ts — fetchDataProcessorMetadata()

dataanalysis_dataprocessors/{id}/process

  • Description: Run a data processor; optional query string of parameter values.
  • Method: GET
  • Used in: src/utils/functions/serverApi.ts — fetchDataProcessorProcess()

dataanalysis_dataprocessorcollectors?processor={id} | ?collector={id}

  • Description: Processor↔collector link records; resolves linked processors/collectors.
  • Method: GET
  • Used in:
    • src/utils/functions/serverApi.ts — fetchProcessorCollectorLinked()
    • src/app/[locale]/data-collector/actions.ts — getDataCollectorLinkedProcessors()

dataanalysis_dataprocessorcollectors

  • Description: Link a processor to a collector.
  • Method: POST
  • Used in: src/utils/functions/serverApi.ts — linkProcessorCollector()
  • Request Body: 
    { "processor": "string", "collector": "string" }

keyvaluestore_keyvalues

  • Description: Per-user key/value store for persisted listing & filter preferences. Accessed through the bundle’s useKVS hook (getKVS/createKVS/updateKVS/deleteKVS). Resource name comes from NEXT_PUBLIC_KVS_API_RESOURCE_NAME (default keyvaluestore_keyvalues).
  • Methods: GET (list by key), POST (create), PUT (update), DELETE
  • Used in:
    • src/components/ReportListing/index.tsx — Fields dropdown save/reset (key report-widget-<widgetId>-listedFields)
    • src/components/ReportFilters/index.tsx — custom filters & saved filter state/values

Internal API Routes

Next.js API routes within the report app.

Status Routes

Backed by @phpcreation/frontend-status-react-nextjs-bundle. Each resolves the tenant from the host and returns JSON.

/api/status

  • Description: Basic status.
  • Method: GET
  • Location: src/app/api/status/route.ts

/api/status/all

  • Description: Comprehensive status (app/version info, API, configs, cache, user token).
  • Method: GET
  • Location: src/app/api/status/all/route.ts

/api/status/api

  • Description: External PHPR API connection status.
  • Method: GET
  • Location: src/app/api/status/api/route.ts

/api/status/configs

  • Description: Configuration service status.
  • Method: GET
  • Location: src/app/api/status/configs/route.ts

/api/status/cache

  • Description: Cache table status (AppCache / ConfigCache).
  • Method: GET
  • Location: src/app/api/status/cache/route.ts

/api/status/user-token/check

  • Description: Validate the user token (from currentUser cookie).
  • Method: GET
  • Location: src/app/api/status/user-token/check/route.ts

/api/status/user-token/display

  • Description: Decoded user-token details.
  • Method: GET
  • Location: src/app/api/status/user-token/display/route.ts

/api/status/user-token/expected

  • Description: Expected token structure/claims for the tenant.
  • Method: GET
  • Location: src/app/api/status/user-token/expected/route.ts

Cache Management

/api/clear-cache

  • Description: Clear cache tables (requires ROLE_ADMIN).
  • Method: DELETE
  • Location: src/app/api/clear-cache/route.ts

Auth / OAuth

/api/config-login

  • Description: Configuration-based login (delegates to configLogin() in the config bundle).
  • Method: POST
  • Location: src/app/api/config-login/route.ts

/api/logout

  • Description: Clear auth cookies and redirect to login.
  • Method: POST
  • Location: src/app/api/logout/route.ts

/api/oauth/authorize

  • Description: Start the OAuth authorization flow.
  • Method: GET
  • Location: src/app/api/oauth/authorize/route.ts

/api/oauth/callback

  • Description: OAuth redirect/callback handler.
  • Method: GET
  • Location: src/app/api/oauth/callback/route.ts

Misc

/api/error-catalog

  • Description: Error catalog lookup.
  • Method: GET
  • Location: src/app/api/error-catalog/route.ts

/api/sentry-example-api

  • Description: Sentry example/test endpoint (demo page only).
  • Method: GET
  • Location: src/app/api/sentry-example-api/route.ts
Last updated on
Creating a reportAuthorization