rafik.
العربية

Phone application

API development

OpenAPI reference and safe development guidance for Rafik APIs.

Participant correction history

On updated backends, authorized calendar detail accepts event id, view=trainer, historyOnly=true, historyMember, historyKind=attendance|results and historyOffset. It returns items (up to 25) and next, including actor attribution, timestamp and the original/changed attendance or score version. The event's current staffing and participant boundary is checked for every read. These parameters and response schemas are in the canonical OpenAPI contract. Existing write/retry semantics remain unchanged.

OpenAPI contract

The backend exports a Swagger-compatible OpenAPI 3.1 JSON document from each updated university instance at GET /v1/openapi.json. It is an unauthenticated description of the supported coach field API subset; it contains no account, roster or athlete data.

Open Swagger UI

On a backend revision containing the viewer, open /v1/docs directly on the API origin, or /api/v1/docs on a Compose self-hosted installation. For default local development, use http://127.0.0.1:55331/v1/docs after starting or restarting the updated backend. The landing site documents this viewer; your institution's backend serves it.

  1. In local development, expand POST /v1/mobile/auth/login and choose Try it out. Use a synthetic coach account.
  2. Copy the response's access_token into Authorize.
  3. Explore the supported coach endpoints. The viewer supplies X-Rafik-Client: android, omits browser cookies and targets the current instance.

Authorization clears on refresh. Assets are bundled locally, the external validator is disabled and tokens are not persisted. With NODE_ENV=production, Swagger is reference-only and Try it out is disabled. API permissions still apply independently. Do not use real athlete or health information in examples.

Supported subset

The current contract describes native login, session validation, refresh and logout, role-context lookup, bounded coach calendar reads, and attendance/result/event-finish command shapes. It is not a complete inventory of every legacy or web-only API. The broader maintained route reference is in the Rafik source repository.

Authentication

The native client uses X-Rafik-Client: android with an opaque bearer session. Access tokens are short-lived; refresh tokens rotate. Native requests do not use the browser cookie session. Use HTTPS for remote instances. The web cookie and origin rules remain separate.

Writes, retries and errors

Use the documented operation ID and current revision for each write. After an uncertain network result, retry the exact same ID and payload. A changed command requires a new ID only after the earlier result is known. The server rechecks current role, assignment, resource and revision before applying or replaying commands. Handle validation, authentication, forbidden, unavailable, conflict, rate-limit and service errors distinctly.

Scope and privacy

The mobile contract supports the coach-first Stage 7 implementation. Attendance, assessment drafts/results, event completion and offline command replay are implemented locally; API integration and native-device acceptance remain open. The API document does not establish those acceptance gates. Private responses and files are never public caches. Do not put shared API secrets, operator credentials or health information into API examples.

Source and status

Reviewed against the university-first development branch on 18 October 2026. The contract and viewer require the corresponding backend changes to be published and deployed. Older instances may expose the JSON without the viewer. This is development-branch guidance, not a release announcement. See the Stage 7 mobile scope and API implementation reference.