API Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• static/openapi.yaml
• swagger_config.py
• helpers.py
• SECURITY.md
• README.md
• templates/qr_auth.html

The Smart Absen application exposes a RESTful API to handle core functionalities such as user authentication, attendance marking, and data management. The API is designed to be consumed by the web frontend, mobile devices (via QR code sync), and administrative dashboards. All endpoints are documented using the OpenAPI 3.0 standard, and the documentation is accessible via a built-in Swagger UI.

A key architectural feature is the standardization of all API responses. This ensures consistency, simplifies frontend integration, and improves error handling. The API is logically grouped into categories: QR Authentication, Attendance, Employees, Admin, and System, reflecting the modular nature of the application.

Sources: static/openapi.yaml, SECURITY.md:21-37, README.md:120-129

API Documentation with Swagger UI

The project provides interactive API documentation through Swagger UI. This allows developers to explore and test endpoints directly from the browser.

Sources: swagger_config.py, static/openapi.yaml

Configuration

The Swagger UI is configured in swagger_config.py and registered as a blueprint in the main Flask application.

Configuration Key	Value	Description
SWAGGER_URL	/api/docs	The URL to access the Swagger UI.
API_URL	/static/openapi.yaml	The path to the OpenAPI specification file.
app_name	Smart Absen API	The name displayed in the Swagger UI.
docExpansion	list	Controls how the operations are displayed by default. list shows all operations.
syntaxHighlight.theme	monokai	The theme for syntax highlighting in the UI.

Sources: swagger_config.py:7-22

The following diagram shows the flow of how API documentation is served.

This diagram illustrates the process of rendering the Swagger UI documentation.
Sources: swagger_config.py, static/openapi.yaml

Standardized API Response

All API endpoints return a standardized JSON response format, which is managed by the api_response function in helpers.py. This ensures consistency for clients.

The standard response structure is as follows:

{
    "success": true,
    "status": "success",
    "message": "Operation completed",
    "data": {...},
    "timestamp": "2025-12-07T17:45:00"
}

Field	Type	Description
success	boolean	true if the operation was successful, false otherwise.
status	string	A string representation of the status (e.g., "success", "error").
message	string	A human-readable message describing the result.
data	object/array	The payload of the response. Can be an object, an array, or null.
timestamp	string	The ISO 8601 timestamp when the response was generated.

Sources: SECURITY.md:21-37, helpers.py

An example usage of this helper function in an endpoint:

from helpers import api_response

@app.route('/api/test')
def test():
    try:
        data = {'message': 'Hello'}
        return api_response(True, 'Success', data)
    except Exception as e:
        return api_response(False, str(e), status_code=500)

Sources: SECURITY.md:92-100

Endpoint Categories

The API is divided into several categories based on functionality, as defined by the tags in the OpenAPI specification.

Sources: static/openapi.yaml:18-33

QR Authentication

These endpoints manage the cross-device synchronization process, allowing a user to authenticate on a primary device (e.g., a laptop) by scanning a QR code with a secondary device (e.g., a mobile phone).

Method	Endpoint	Description
GET	/auth	Renders the page with the QR code for scanning.
GET	/verify	Verifies a QR code entered manually.
GET	/api/qr_sync_status	A polling endpoint for the primary device to check if the QR has been scanned.
POST	/api/accept_qr_sync	Called by the primary device to accept the sync initiated by the mobile device.
GET	/api/refresh_qr	Generates a new QR code and unit code.
POST	/api/clear_qr_session	Clears the session after successful attendance to prevent auto-redirect.

Sources: static/openapi.yaml:35-120, templates/qr_auth.html

The following sequence diagram illustrates the QR synchronization flow:

This diagram shows the interaction between the user's laptop, the server, and the user's mobile device to complete QR-based authentication.
Sources: static/openapi.yaml:35-100, templates/qr_auth.html:300-400

Attendance

These endpoints are for marking and retrieving employee attendance records.

Method	Endpoint	Description
GET	/web_attendance	Renders the attendance page with face recognition via webcam.
POST	/mark_attendance_mobile	Submits attendance from a mobile device with a captured face image.
GET	/api/get_attendance_data	Retrieves attendance records with optional filters.

Sources: static/openapi.yaml:123-178

Mobile Attendance Flow

The /mark_attendance_mobile endpoint receives a Base64 encoded image and processes it for face recognition.

This flowchart shows the logic for processing an attendance request from a mobile device.
Sources: static/openapi.yaml:137-158

Attendance Data Schema

The Attendance and AttendanceResponse schemas define the structure of attendance-related data.

Attendance Schema

Field	Type	Description
id	integer	Unique ID of the attendance record.
employee_id	integer	Foreign key to the employee.
employee_name	string	Name of the employee.
date	string (date)	Date of attendance.
time_in	string (time)	Clock-in time.
time_out	string (time)	Clock-out time.
status	string	Attendance status (e.g., hadir, telat).

Sources: static/openapi.yaml:313-333

Employees

Endpoints for managing employee data. These are typically restricted to admin users.

Method	Endpoint	Description	Security
GET	/api/employees	Retrieves a list of all employees.	None
POST	/api/employees	Adds a new employee with training photos.	Admin
GET	/api/employees/{id}	Retrieves a single employee by ID.	None
PUT	/api/employees/{id}	Updates an employee's details.	Admin
DELETE	/api/employees/{id}	Deletes an employee.	Admin

Sources: static/openapi.yaml:181-262

Admin

Endpoints for administrative operations, such as training the machine learning model.

Method	Endpoint	Description	Security
GET	/admin/login	Renders the admin login page.	None
POST	/admin/login	Processes admin login credentials.	None
GET	/admin/dashboard	Renders the main admin dashboard.	Admin
POST	/api/train_model	Re-trains the InsightFace model with the latest data.	Admin

Sources: static/openapi.yaml:265-310

System

Endpoints for system monitoring and health checks.

Method	Endpoint	Description
GET	/health	Checks the health of system components like the database and ML model.

The /health endpoint returns a JSON object indicating the status of critical services.

Example Health Check Response:

{
  "status": "healthy",
  "timestamp": "2025-12-07T12:00:00Z",
  "database": "connected",
  "model": "available",
  "version": "2.0.0"
}

Sources: static/openapi.yaml:313-333

Summary

The API for the Smart Absen system is a well-structured and documented interface that powers the application's core features. Through the use of OpenAPI/Swagger, standardized responses, and logical grouping, the API is made maintainable and easy for developers to integrate with. The endpoints cover everything from complex cross-device QR authentication to simple health checks, providing a comprehensive backend for a modern attendance system.

Sources: README.md, SECURITY.md, static/openapi.yaml