From 8358cc4d14e2d286ad01892838d5a9c03b6e5697 Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Thu, 20 Aug 2026 18:14:16 +0330 Subject: [PATCH] docs(api): approve CSV export limits --- docs/API-SPEC.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/API-SPEC.md b/docs/API-SPEC.md index 534dc6a..245c445 100644 --- a/docs/API-SPEC.md +++ b/docs/API-SPEC.md @@ -144,7 +144,7 @@ The filename contains the view, canonical period id, and generation timestamp. I - Export generation has a 60-second server deadline. A timeout returns a Problem Details response if headers are unsent; a connection terminated after streaming begins is incomplete and must never be presented as a successful audited export. - Export requests default to 3 per 10 minutes with burst 1 in independent authenticated-user and merchant buckets. A rejection returns `429` with `Retry-After` before query/stream work begins. -The row/byte/deadline/export-throttle defaults are proposed MVP policy and are called out for explicit approval under Remaining product questions. +The row/byte/deadline/export-throttle values are approved MVP policy. ## SSE events and recovery @@ -223,12 +223,12 @@ Approved existing limits remain unchanged: - SSE: two concurrent streams/user and four/merchant; - section attempt: 60 seconds and at most two transient retries. -Proposed API boundary defaults: +API boundary limits: -- JSON request body: 16 KiB maximum; requests with no defined body reject non-empty bodies; -- request target/query string: 8 KiB maximum at the public edge; -- detail page: default 25, maximum 100; -- CSV: 100,000 rows, 50 MiB estimated uncompressed output, 60 seconds, and 3 requests/10 minutes burst 1 per user and merchant. +- Proposed: JSON request body is limited to 16 KiB; requests with no defined body reject non-empty bodies. +- Proposed: request target/query string is limited to 8 KiB at the public edge. +- Approved: detail pages default to 25 rows and cannot exceed 100. +- Approved: synchronous CSV export is limited to 100,000 rows, 50 MiB estimated uncompressed output, and 60 seconds, with 3 requests/10 minutes and burst 1 per user and merchant. Limits are enforced before enqueuing or expensive work where possible. User and merchant buckets are independent; exhausting one never consumes another tenant's allowance. @@ -268,13 +268,19 @@ Correlate `requestId`, authenticated user/merchant internal ids, run id, section - Ask first: change an endpoint/schema/error code, expose a new field/filter/detail/export, change a rate/size/retention limit, add a role, change cookie/CORS/CSRF behavior, or add a cross-service/public interface. - Never: accept merchant id as authority; expose payer tokens, credentials, peer rows, internal errors, or raw infrastructure state; silently broaden invalid filters; return partial CSV as success; let OpenAPI drift behind implementation. +## Resolved API decisions + +- Merchant-facing detail CSV export is synchronous in the MVP and honors the current authorized tenant scope and approved filters. +- CSV export is capped at 100,000 rows, 50 MiB estimated uncompressed output, and a 60-second deadline. +- CSV export is limited to 3 requests per 10 minutes with burst 1 in independent authenticated-user and merchant buckets. + ## Remaining product questions -1. Approve or revise the proposed CSV policy: synchronous export, 100,000-row and 50-MiB uncompressed caps, 60-second deadline, and 3 requests/10 minutes with burst 1 per user and merchant. -2. Approve UTF-8 BOM output for spreadsheet compatibility and stable ASCII column headers, or require localized Persian header names. -3. Define retention and operator access policy for analytics-access and CSV-export audit records; Identity's 30-day demo-auth retention does not automatically cover these events. -4. Confirm whether terminal identifiers may be shown/exported as their existing opaque source reference or require a separate merchant-facing display alias. -5. Choose the production base URI used for dereferenceable Problem Details `type` documentation; `https://api.zarinpal.example/problems/...` is a non-production placeholder in the draft contract. +1. Approve UTF-8 BOM output for spreadsheet compatibility and stable ASCII column headers, or require localized Persian header names. +2. Define retention and operator access policy for analytics-access and CSV-export audit records; Identity's 30-day demo-auth retention does not automatically cover these events. +3. Confirm whether terminal identifiers may be shown/exported as their existing opaque source reference or require a separate merchant-facing display alias. +4. Choose the production base URI used for dereferenceable Problem Details `type` documentation; `https://api.zarinpal.example/problems/...` is a non-production placeholder in the draft contract. +5. Approve or revise the proposed public-edge request limits: 16 KiB for JSON bodies and 8 KiB for the request target/query string. ## Standards references