# Frontend API Reference Base URL: `http://localhost/php/ar/api.php` Required headers for all requests (add these to every example): - `Content-Type: application/json` (for requests with body) - `Accept: application/json` - `X-Tenant-ID: ` General pagination/query params: `?limit=50&offset=0`, foreign-key filters (e.g. `?event_id=3`). Response pseudocode for single-resource objects (example): { "id": number, "name": string } --- **Categories** - GET list ``` GET http://localhost/php/ar/api.php/categories Accept: application/json X-Tenant-ID: ``` Response (array): [ { "id": number, "slug": string|null, "name": string, "border_color": string|null, "created_at": string, "modified_at": string }, ... ] - GET by id ``` GET http://localhost/php/ar/api.php/categories/{id} Accept: application/json X-Tenant-ID: ``` - POST create ``` POST http://localhost/php/ar/api.php/categories Content-Type: application/json Accept: application/json X-Tenant-ID: { "name": "string", "border_color": "string|null" } ``` Response: created category object (same fields as GET). - PUT/PATCH update ``` PUT http://localhost/php/ar/api.php/categories/{id} Content-Type: application/json Accept: application/json X-Tenant-ID: { "name": "string", "border_color": "string|null" } ``` - DELETE ``` DELETE http://localhost/php/ar/api.php/categories/{id} Accept: application/json X-Tenant-ID: ``` Response: `{ "success": boolean, "deleted_id": number }` --- **Events** - GET list ``` GET http://localhost/php/ar/api.php/events Accept: application/json X-Tenant-ID: ``` Response item fields: { "id": number, "slug": string|null, "name": string, "start_time": string|null, "description": string|null, "race_start_location_id": number|null, "created_at": string, "modified_at": string } - GET by id ``` GET http://localhost/php/ar/api.php/events/{id} Accept: application/json X-Tenant-ID: ``` - POST create ``` POST http://localhost/php/ar/api.php/events Content-Type: application/json Accept: application/json X-Tenant-ID: { "name": "string", "start_time": "YYYY-MM-DD HH:MM:SS" | null, "description": "string|null", "race_start_location_id": number|null } ``` - PUT/PATCH update ``` PUT http://localhost/php/ar/api.php/events/{id} Content-Type: application/json Accept: application/json X-Tenant-ID: { /* same fields as POST */ } ``` - DELETE ``` DELETE http://localhost/php/ar/api.php/events/{id} Accept: application/json X-Tenant-ID: ``` Note: `events` may be marked non-deletable in backend config. - Subresources (examples): ``` GET /events/{id}/courses GET /events/{id}/teams GET /events/{id}/locations ``` Include `Accept` and `X-Tenant-ID` headers on all. --- **Courses** - GET list ``` GET http://localhost/php/ar/api.php/courses Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "slug": string|null, "name": string, "distance": number, "event_id": number|null, "created_at": string, "modified_at": string } - GET by id ``` GET http://localhost/php/ar/api.php/courses/{id} Accept: application/json X-Tenant-ID: ``` - POST create ``` POST http://localhost/php/ar/api.php/courses Content-Type: application/json Accept: application/json X-Tenant-ID: { "name": "string", "distance": number, "event_id": number|null } ``` - PUT/PATCH update ``` PUT http://localhost/php/ar/api.php/courses/{id} Content-Type: application/json Accept: application/json X-Tenant-ID: { /* same fields as POST */ } ``` - DELETE ``` DELETE http://localhost/php/ar/api.php/courses/{id} Accept: application/json X-Tenant-ID: ``` - GET legs for a course ``` GET http://localhost/php/ar/api.php/courses/{id}/legs Accept: application/json X-Tenant-ID: ``` --- **Legs** - GET list ``` GET http://localhost/php/ar/api.php/legs Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "slug": string|null, "course_id": number, "name": string, "type": string, "total_checkpoints": number, "order_no": number, "ends_at": string|null, "special_checkpoints": object|null, "route_gpx": string|null, "color": string|null, "distance_text": string|null, "altitude_gain": string|null, "start_location_id": number|null, "end_location_id": number|null, "created_at": string, "modified_at": string } - GET by id, POST, PUT, DELETE follow same header pattern as above (include `X-Tenant-ID`). - GET checkpoints and special_checkpoints for a leg: ``` GET /legs/{id}/checkpoints GET /legs/{id}/special_checkpoints ``` Include `X-Tenant-ID`. --- **Leg Checkpoints (`leg_checkpoints`)** - GET list ``` GET http://localhost/php/ar/api.php/leg_checkpoints Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "leg_id": number, "location_id": number, "order_no": number, "created_at": string, "modified_at": string } - POST create ``` POST http://localhost/php/ar/api.php/leg_checkpoints Content-Type: application/json Accept: application/json X-Tenant-ID: { "leg_id": number, "location_id": number, "order_no": number } ``` - PUT/PATCH/DELETE follow the same header pattern. --- **Leg Special Checkpoints (`leg_special_checkpoints`)** - GET list ``` GET http://localhost/php/ar/api.php/leg_special_checkpoints Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "leg_id": number, "name": string, "description": string|null, "created_at": string, "modified_at": string } - POST create ``` POST http://localhost/php/ar/api.php/leg_special_checkpoints Content-Type: application/json Accept: application/json X-Tenant-ID: { "leg_id": number, "name": "string", "description": "string|null" } ``` --- **Locations** - GET list ``` GET http://localhost/php/ar/api.php/locations Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "slug": string|null, "name": string, "short_name": string|null, "type": string|null, "lat": number|null, "lng": number|null, "images": object|null, "created_at": string, "modified_at": string } - POST create / PUT / DELETE follow same header pattern (include `X-Tenant-ID`). - GET transition_times for location ``` GET /locations/{id}/transition_times Accept: application/json X-Tenant-ID: ``` --- **Teams** - GET list ``` GET http://localhost/php/ar/api.php/teams Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "slug": string|null, "name": string, "bib_number": string|null, "category": string|null, "course_id": number|null, "event_id": number|null, "withdrawn": boolean, "created_at": string, "modified_at": string, "number": number|null, "biography": string|null, "category_id": number|null } - POST create ``` POST http://localhost/php/ar/api.php/teams Content-Type: application/json Accept: application/json X-Tenant-ID: { /* team fields per above */ } ``` - PUT/PATCH/DELETE follow same header pattern. - Subresources (examples): ``` GET /teams/{id}/team_members POST /teams/{id}/team_members GET /teams/{id}/team_messages POST /teams/{id}/team_messages GET /teams/{id}/progress GET /teams/{id}/team_track POST /teams/{id}/team_track ``` Include `X-Tenant-ID` for all. --- **Team Members** - GET list ``` GET http://localhost/php/ar/api.php/team_members Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "slug": string|null, "team_id": number, "name": string, "dropped_out": boolean, "created_at": string, "modified_at": string } - POST create ``` POST http://localhost/php/ar/api.php/team_members Content-Type: application/json Accept: application/json X-Tenant-ID: { "team_id": number, "name": "string", "dropped_out": boolean|null } ``` --- **Team Device (`team_device`)** - GET list ``` GET http://localhost/php/ar/api.php/team_device Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "team_id": number, "device_id": number, "created_at": string, "modified_at": string } - POST create ``` POST http://localhost/php/ar/api.php/team_device Content-Type: application/json Accept: application/json X-Tenant-ID: { "team_id": number, "device_id": number } ``` --- **Transition Times** - GET list ``` GET http://localhost/php/ar/api.php/transition_times Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "team_id": number, "name": string, "location_id": number, "time": string, "created_at": string, "modified_at": string } - POST create / PUT / DELETE follow same header pattern. --- **Team Progress** - GET list ``` GET http://localhost/php/ar/api.php/team_progress Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "team_id": number, "leg_id": number, "checkpoints_collected": number|null, "finish_time": string|null, "transition_in": string|null, "transition_out": string|null, "meta": object|null, "created_at": string, "modified_at": string } - POST create / PUT / DELETE follow same header pattern. - Subresources (examples): ``` GET /team_progress/{id}/transition_times GET /team_progress/{id}/special_checkpoint_events ``` --- **Special Checkpoint Events** - GET list ``` GET http://localhost/php/ar/api.php/special_checkpoint_events Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "team_progress_id": number, "name": string, "occurred_at": string|null, "checkpoints_before": number|null, "created_at": string, "modified_at": string } - POST create / PUT / DELETE follow same header pattern. --- **Team Messages** - GET list ``` GET http://localhost/php/ar/api.php/team_messages Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "team_id": number, "sender": string, "text": string, "timestamp": string|null, "created_at": string } - POST create ``` POST http://localhost/php/ar/api.php/team_messages Content-Type: application/json Accept: application/json X-Tenant-ID: { "team_id": number, "sender": "string", "text": "string", "timestamp": "YYYY-MM-DD HH:MM:SS" | null } ``` --- **Race (read-only)** - GET by event id ``` GET http://localhost/php/ar/api.php/race?event_id={event_id} Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "event_id": number, "data": object|null, "created_at": string, "modified_at": string } --- Notes: - All examples MUST include `X-Tenant-ID` header with the tenant identifier. - JSON columns (`images`, `meta`, `special_checkpoints`, `race.data`) should be sent/received as JSON objects/arrays. - Boolean DB fields (tinyint) map to booleans in the frontend. - If the backend disables certain operations (e.g., deleting events) the API will return an error; check `arconfig.php` for intended behavior. --- **Devices & Team-Device** We expose full CRUD for `device` and `team_device`. `team` subkeys include `team_device` and `team_track`. `device` subkeys include `device_latest`, `device_interval`, and `device_events` (read-only). Note: include `X-Tenant-ID` on all requests below. **Device** - GET list ``` GET http://localhost/php/ar/api.php/device Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "serial": string, "imei": string, "created_at": string, "modified_at": string } - GET by id ``` GET http://localhost/php/ar/api.php/device/{id} Accept: application/json X-Tenant-ID: ``` - POST create ``` POST http://localhost/php/ar/api.php/device Content-Type: application/json Accept: application/json X-Tenant-ID: { "serial": "string", "imei": "string" } ``` - PUT/PATCH update ``` PUT http://localhost/php/ar/api.php/device/{id} Content-Type: application/json Accept: application/json X-Tenant-ID: { /* same fields as POST */ } ``` - DELETE ``` DELETE http://localhost/php/ar/api.php/device/{id} Accept: application/json X-Tenant-ID: ``` **Team Device (`team_device`)** - GET list ``` GET http://localhost/php/ar/api.php/team_device Accept: application/json X-Tenant-ID: ``` Fields: { "id": number, "team_id": number, "device_id": number, "created_at": string, "modified_at": string } - GET by id ``` GET http://localhost/php/ar/api.php/team_device/{id} Accept: application/json X-Tenant-ID: ``` - POST create ``` POST http://localhost/php/ar/api.php/team_device Content-Type: application/json Accept: application/json X-Tenant-ID: { "team_id": number, "device_id": number } ``` - PUT/PATCH update ``` PUT http://localhost/php/ar/api.php/team_device/{id} Content-Type: application/json Accept: application/json X-Tenant-ID: { /* same fields as POST */ } ``` - DELETE ``` DELETE http://localhost/php/ar/api.php/team_device/{id} Accept: application/json X-Tenant-ID: ``` **Read-only device resources** The following resources are intended read-only in the frontend (GET-only examples provided): - `device_latest` (latest known positions per serial/imei) ``` GET http://localhost/php/ar/api.php/device_latest Accept: application/json X-Tenant-ID: ``` Fields include `id`, `serial`, `imei`, `object_name`, `object_desc`, `event_at`, `latitude`, `longitude`, `speed`, `altitude`, `direction`, `started`, `hardware`, `raw_message`, `created_at`, `modified_at`. - `device_events` (historical events) ``` GET http://localhost/php/ar/api.php/device_events Accept: application/json X-Tenant-ID: ``` Fields include `id`, `serial`, `imei`, `object_name`, `event_at`, `latitude`, `longitude`, `speed`, `altitude`, `started`, `raw_message`, `created_at`, `modified_at`. - `device_interval` (aggregated intervals) ``` GET http://localhost/php/ar/api.php/device_interval Accept: application/json X-Tenant-ID: ``` Fields include `id`, `serial`, `imei`, `interval_start`, `interval_end`, `points_count`, `min_speed`, `max_speed`, `last_event_at`, `last_latitude`, `last_longitude`, `created_at`, `modified_at`. **Team subkeys** When retrieving a `team` you can fetch related `team_device` and `team_track` entries via the subresource endpoints: ``` GET /teams/{id}/team_device GET /teams/{id}/team_track ``` Include `X-Tenant-ID` header. **Device subkeys** When retrieving a `device` you may want to query related read-only resources: ``` GET /device/{id}/device_latest GET /device/{id}/device_events GET /device/{id}/device_interval ``` Include `X-Tenant-ID` header.