Skip to content

README.md

Latest commit

 

History

History
69 lines (56 loc) · 3.36 KB

README.md

File metadata and controls

69 lines (56 loc) · 3.36 KB
Raw

SaQshi API Developer Documentation

This documentation explains the API layer for developers who need to maintain, debug, or extend SaQshi. It intentionally documents both the HTTP contract and the implementation path behind each endpoint.

Documentation map

Document Scope
Endpoint inventory Complete list of API endpoint source files, grouped by module.
Source reference Generated reference for every API PHP file and JSON configuration file.
saqshi_postman_collection.json Importable Postman API testing collection.
saqshi_local_postman_environment.json Importable Postman local environment variables.
assessment.md Assessment lifecycle, assessment endpoints, validation, and data flow.
assessor.md State-led assessor profile, facility mapping, and assessor assessment start flow.
auth.md Authentication, session, CSRF, and access control endpoints.
framework.md Framework metadata endpoints.
performance.md Indicator, KPI, outcome, and performance dashboard endpoints.
certification.md Certification lifecycle endpoints.
state.md State dashboard and administrative reporting endpoints.
supporting-apis.md Files, reports, chat, and admin endpoints.
core-and-services.md Shared core classes and services used by the endpoint files.

Files without a corresponding module guide are listed in the inventory and are scheduled for the next documentation pass. Do not treat an inventory entry as a complete API specification.

The source reference is generated by tools/generate-api-documentation.php and must be regenerated whenever API implementation files change.

Request lifecycle

Client request
  -> public API entry point / route dispatcher
  -> bootstrap/auth include
  -> method and input validation
  -> service class and/or prepared database query
  -> Response helper JSON envelope

Most endpoint files include either api/auth_api.php or a module-specific bootstrap file. These files establish the common runtime, session context, authentication and response utilities before business logic executes.

Conventions used in this guide

  • Source is the repository-relative PHP file that implements the endpoint.
  • URL is inferred from the file path unless a router or caller overrides it.
  • Session-derived input means the value is obtained from SessionManager, rather than trusted from the request body.
  • Why it exists describes the business responsibility, not merely the code.
  • Endpoint documentation distinguishes public endpoints from internal helpers such as _common.php and _bootstrap.php.

Safe extension checklist

  1. Reuse the module's bootstrap/authentication pattern.
  2. Require and validate the expected HTTP method before processing input.
  3. Obtain facility/user identity from the session where authorization requires it.
  4. Use prepared statements for every database value.
  5. Keep response envelopes consistent through Response helpers.
  6. Record any needed audit/history data before changing a lifecycle state.
  7. Add the new endpoint to this documentation and to the Postman collection.

The assessment module also provides a facility-scoped FHIR R4 MeasureReport export. Its machine-readable contract is included in openapi.yaml and its request is included in the Postman collection.