Make safe idempotent writes

Waqar write access is separately entitled, rolled out, and authorized. Do not deploy write code until the school confirms that the exact write scopes are effective.

• Create or update a student.
• Create, update, or end a session.
• Create or update the supplied students’ session attendance in one batch; omitted students remain unchanged.
• Record a recitation in a session.

Learning Plans are read-only in API v1.

• Use Content-Type: application/json.
• Keep the complete body at or below 1 MiB.
• Send only fields defined by the current schema; unknown fields are rejected.
• Use documented enum, UUID, date, Quran-range, and rating constraints.
• Attendance batches contain 1–1,000 unique students.
• In a patch, an omitted field means “leave unchanged”; an explicit supported null can clear a nullable field.

POST creation and attendance PUT require an Idempotency-Key. The value must be 1–255 visible ASCII characters (! through ~; spaces are not allowed). Student and session patches and the session-end action accept one optionally.

For each logical operation:

1. Generate a high-entropy value in the calling service.
2. Persist it with the pending job before sending.
3. Send the same value with the exact same method, route, query, and body for a retry.
4. Keep it secret from logs, traces, URLs, and user interfaces.
5. Retain the mapping through Waqar’s seven-day replay window.

An exact successful replay returns the stored response. Reusing the value for a different request returns 409 idempotency_key_conflict. A concurrent duplicate can return 409 idempotency_request_in_progress; wait for Retry-After and retry the exact request.

1. Read and validate prerequisite identifiers in the same tenant.
2. Validate the outgoing body locally against OpenAPI.
3. Send the minimum-scope key and idempotency value.
4. On 201, store the returned data.id and Location.
5. On 200, reconcile the returned resource.
6. On 422, correct the business input; do not retry unchanged.
7. On 409, distinguish lifecycle conflict from idempotency behavior.
8. On uncertain transport failure, retry only with the original idempotency value and identical request.
9. Follow with a read when the integration needs durable confirmation.

Never turn a rejected write into undocumented mutations. See errors and quotas and resources.