Skip to main content

11.1 Platform: health, readiness, OpenAPI

GET /api/v1/health​

  • Purpose. Confirms the application process can answer requests. Does not check dependencies.
  • Authentication. None.
  • Role. None.
  • Parameters. None. Send Accept: text/html to receive a human-readable page instead of JSON.
  • Body. None.

Example:

curl -s https://dffms.org/api/v1/health

Response (200):

{
  "data": {
    "status": "ok",
    "service": "dffms-web",
    "scope": "application-liveness",
    "timestamp": "2026-10-26T08:00:00.000Z"
  },
  "error": null,
  "requestId": "<request-id>"
}
  • Errors. None defined beyond unexpected 500.
  • Side effects. None.

GET /api/v1/ready​

  • Purpose. Reports whether the database answers a readiness query, and whether optional email and Google sign-in are configured.
  • Authentication. None.
  • Parameters. None.
curl -s https://dffms.org/api/v1/ready

Response (200):

{
  "data": {
    "status": "ready",
    "dependencies": {
      "database": "ready",
      "email": "configured",
      "googleOAuth": "disabled"
    }
  },
  "error": null,
  "requestId": "<request-id>"
}
  • Errors. 503 NOT_READY ("A required dependency is unavailable") when the database query fails.
  • Side effects. None.

GET /api/v1/openapi​

  • Purpose. Returns the OpenAPI 3.1 description of this API.
  • Authentication. None.
  • Response. Raw OpenAPI JSON (no envelope). Headers: Cache-Control: public, max-age=300, s-maxage=3600, X-Content-Type-Options: nosniff.
curl -s https://dffms.org/api/v1/openapi | head -c 300
  • Notes. The document does not list /api/v1/contact or OPTIONS.