API modern DX baseline reference
This page documents the cross-cutting wire contract for the MapleGather REST API: idempotency, rate limits, cursor pagination, batch operations, and the RFC 7807 error format. These behaviors apply uniformly across all API endpoints.
Idempotency
Section titled “Idempotency”Use the Idempotency-Key header on every POST and PATCH request to safely retry without side effects.
| Detail | Value |
|---|---|
| Header name | Idempotency-Key |
| Value format | Any unique string (UUID recommended) |
| Cache TTL | 24 hours from first request |
| Same key + same body | Returns the cached response (no re-execution) |
| Same key + different body | 409 (the code is operation-specific; check the interactive docs for the operation you’re calling) |
If a request times out before you receive a response, resend with the same Idempotency-Key. The server de-duplicates the operation.
Rate limits
Section titled “Rate limits”Rate-limit state is communicated through response headers present on every response.
| Header | Meaning |
|---|---|
X-RateLimit-Limit |
Maximum requests allowed in the current window |
X-RateLimit-Remaining |
Requests remaining in the current window |
X-RateLimit-Reset |
Unix timestamp when the window resets |
When the limit is exceeded, the response is 429 Too Many Requests with a Retry-After header (seconds to wait before retrying).
Burst tolerance: up to 200 requests over any 10-second window are accepted before rate limiting applies. Implement exponential backoff with jitter for retry logic. Include the original Idempotency-Key when retrying a POST/PATCH that returned 429.
Cursor pagination
Section titled “Cursor pagination”All list endpoints use cursor-based pagination. Do not use offset pagination.
| Parameter / field | Description |
|---|---|
limit (query param) |
Maximum items per page. Capped at 100. |
cursor (query param) |
Pass the nextCursor value from the previous response to fetch the next page. Omit for the first page. |
nextCursor (response field, inside PageEnvelope) |
Present when more pages exist; absent (or null) on the last page. |
If a cursor becomes invalid, restart pagination from the first page (omit the cursor parameter).
Batch operations
Section titled “Batch operations”POST /bc/v1/orgs/{orgId}/batch executes up to 100 operations in a single HTTP round-trip.
| Detail | Value |
|---|---|
| Operation ID | batch_create |
| Max operations per request | 100 |
| Execution model | Non-atomic at M1 — a failure in one operation does not roll back others |
| Response | An array of per-operation results, each with its own status and body |
| Authentication | Bearer token (same scopes as if the operations were called individually) |
| Idempotency | Apply an Idempotency-Key to the batch request as a whole |
Use batch to reduce round-trip latency for bulk reads or writes. Check each per-operation result independently — do not assume all succeeded because the HTTP status is 200.
RFC 7807 error format
Section titled “RFC 7807 error format”All 4xx and 5xx responses use Content-Type: application/problem+json.
Problem schema (all errors):
{ "type": "https://maplegather.com/errors/not-found", "title": "Resource not found", "status": 404, "code": "not_found", "detail": "Member with id 'abc123' does not exist", "instance": "urn:trace:01HZ8M9ABCDEM"}ValidationProblem schema (field validation errors — 422):
{ "type": "https://maplegather.com/errors/validation", "title": "Validation failed", "status": 422, "code": "validation.failed", "violations": [ { "field": "email", "message": "must be a valid email address" } ]}Parse error responses by status code first, then by type for fine-grained handling.