Skip to content

RESTful report generation and download endpoint design

This page outlines the design for handling asynchronous report generation and file retrieval within a RESTful architecture. The pattern separates the initiation of the report creation process from the actual downloading of the file, allowing for long-running processing times without blocking the client's HTTP connection.^[001-TODO__code-getway.md]

Core Endpoints

The design relies on two primary endpoints: one for triggering the report job and another for retrieving the result^[001-TODO__code-getway.md].

  • GET /v1/report: This endpoint accepts a reportType and search parameters to initiate the report generation process^[001-TODO__code-getway.md].
  • GET /v1/report/download: This endpoint accepts a reportType and the specific report id (generated by the previous step) to retrieve the file stream^[001-TODO__code-getway.md].

Workflow Sequence

The process follows a distinct asynchronous flow:

  1. Initiation: The client calls the generation endpoint, passing the desired reportType (e.g., PROXY, PROXY_DOMAIN) and any necessary searchParam filters^[001-TODO__code-getway.md].
  2. Record Creation: The gateway service delegates to a domain service, which in turn calls an internal client (via Feign) to create a report record in the backend system^[001-TODO__code-getway.md]. This ensures the job is queued or processed.
  3. Polling: While not explicitly shown in the code snippet, the implied pattern is that the client uses the returned record ID to check status or proceed to download once ready.
  4. Download: The client requests the file using the ID. The service retrieves the byte array and metadata (e.g., filename suffix) from the backend and constructs a proper HTTP response for the browser to handle the download^[001-TODO__code-getway.md].

Implementation Details

Security and Authorization

Access control is managed dynamically based on the report type^[001-TODO__code-getway.md]. A custom validator, ReportSecurityValidator, is used in conjunction with Spring Security's @PreAuthorize annotation^[001-TODO__code-getway.md]. This validator checks if the authenticated user possesses the specific authority string (e.g., proxy:domain:edit) associated with the requested ReportType enum^[001-TODO__code-getway.md].

Response Construction

The download endpoint constructs the HTTP response to ensure the browser treats the data as a file attachment^[001-TODO__code-getway.md]. * Body: The raw byte array (byte[]) retrieved from the backend is wrapped in a ByteArrayInputStream and exposed as an InputStreamResource^[001-TODO__code-getway.md]. * Headers: The Content-Disposition header is set to attachment; filename="...", and the Content-Type is dynamically derived from the file's extension (e.g., "application/pdf")^[001-TODO__code-getway.md].

Sources

^[001-TODO__code-getway.md]