API integrator checklist

Waqar exposes a versioned school API described by the canonical OpenAPI contract. API access requires an eligible plan, an enabled school feature, a school-issued key, appropriate scopes, and any applicable platform rollout control. Write access is separately controlled and must not be assumed from read access.

1. Ask the school administrator to confirm that API access is available.
2. Define the minimum resources and actions the integration needs.
3. Obtain a dedicated key with the minimum scopes. Do not reuse a person’s password, browser session, or another integration’s key.
4. Retrieve the current contract from /api/openapi.yaml or use the rendered API documentation at /api/docs.
5. Keep the base URL, key, and environment configuration outside source code.

The key secret may be shown only when it is created. Store it in an approved secret manager. Never put it in a browser application, repository, log, screenshot, support message, or wiki page.

Start with a small read-only request. Send the documented authorization header, request JSON, and record the response status plus the request or trace identifier without logging sensitive bodies. Validate responses against the OpenAPI schema and handle pagination wherever the operation defines it.

The school in the credential is the security boundary. Do not try to construct identifiers from another school or infer access from predictable IDs.

Write operations require explicit capability and scopes. For supported create or mutation operations:

• follow the exact request schema;
• use the documented idempotency behavior;
• retry only statuses and methods documented as safe;
• preserve validation and conflict responses for operator review;
• reconcile the result with a follow-up read when appropriate.

Never convert a rejected write into a sequence of undocumented requests.

• Test with non-production or approved fixture data.
• Handle authentication, authorization, validation, conflict, quota, and server failures separately.
• Use bounded backoff and respect quota or retry information.
• Redact credentials and personal data from telemetry.
• Document key ownership, rotation, revocation, incident response, and decommissioning.
• Pin behavior to the published contract, not to an observed undocumented response field.

The full endpoint, scope, pagination, error, quota, and write guides remain release-gated until their matching Arabic and English pages are published.