starcoach-hackathon/zarinpal-analytics-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): approve CSV export limits

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 18:14:16 +03:30
parent b031cfe280
commit 8358cc4d14
1 changed files with 17 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/API-SPEC.md
View File

@@ -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 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. - 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 ## SSE events and recovery
@@ -223,12 +223,12 @@ Approved existing limits remain unchanged:
- SSE: two concurrent streams/user and four/merchant; - SSE: two concurrent streams/user and four/merchant;
- section attempt: 60 seconds and at most two transient retries. - 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; - Proposed: JSON request body is limited to 16 KiB; requests with no defined body reject non-empty bodies.
- request target/query string: 8 KiB maximum at the public edge; - Proposed: request target/query string is limited to 8 KiB at the public edge.
- detail page: default 25, maximum 100; - Approved: detail pages default to 25 rows and cannot exceed 100.
- CSV: 100,000 rows, 50 MiB estimated uncompressed output, 60 seconds, and 3 requests/10 minutes burst 1 per user and merchant. - 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. 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. - 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. - 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 ## 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. 1. Approve UTF-8 BOM output for spreadsheet compatibility and stable ASCII column headers, or require localized Persian header names.
2. 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. 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. 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. 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 ## Standards references