Health Checks

This guide explains how to create, run, update, and manage Health Checks.

Why this matters

• Health checks validate that a backend service is reachable and responding as expected.
• Execute is immediate; Test allows dry-run validation of a definition without saving it.
• A stored Health Check can be executed at any time.

Assumptions

• The examples assume you have a valid Bearer token. If you need help obtaining a token, see [./auth](Auth Guide).
• Base URL for all API calls is https://gateway.production.netfoundry.io/frontdoor
• Expected headers for all API calls:

- Authorization: Bearer YOUR_ACCESS_TOKEN
- Accept: application/hal+json or application/json

Operations

List health checks

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/health-checks?page=0&size=20"

Get a health check

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/health-checks/hc-1

Create a health check

Request example

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "homepage-check",
        "method": "GET",
        "path": "/",
        "expectedStatus": 200
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/health-checks

Response example

{
  "id": "hc-1",
  "name": "homepage-check",
  "enabled": true
}

Execute a health check now

Request example

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/health-checks/hc-1:execute

Response example

{
  "healthCheckId": "hc-1",
  "result": "SUCCESS",
  "status": 200,
  "latencyMs": 120
}

Test a health check definition (dry-run)

Request example

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/health-checks/hc-1:test

Response example

{
  "healthCheckId": "hc-1",
  "result": "SUCCESS",
  "status": 200,
  "latencyMs": 120
}

Partial update a health check

Request example

curl -s -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "enabled": false
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/health-checks/hc-1

Full update of a health check

Request example

curl -s -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "homepage-check",
        "method": "GET",
        "path": "/",
        "expectedStatus": 200,
        "enabled": true
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/health-checks/hc-1

Delete a health check

Request example

curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/health-checks/hc-1

The delete request has an empty response.

Technical Notes

Paths

- GET /frontdoor/\{frontdoorId\}/health-checks[?page=0&size=20]
- GET /frontdoor/\{frontdoorId\}/health-checks/{id}
- POST /frontdoor/\{frontdoorId\}/health-checks
- PATCH /frontdoor/\{frontdoorId\}/health-checks/{id}
- PUT /frontdoor/\{frontdoorId\}/health-checks/{id}
- DELETE /frontdoor/\{frontdoorId\}/health-checks/{id}
- POST /frontdoor/\{frontdoorId\}/health-checks/{id}/execute
- POST /frontdoor/\{frontdoorId\}/health-checks/{id}/test

Common errors

400 Bad Request (client error)

{
  "error": "invalid_request",
  "message": "Value for <property> must be of <type>"
}

Possible reasons include:

• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

401 Unauthorized (missing/expired token)

{
  "error": "unauthorized",
  "message": "Bearer token is missing or invalid"
}

Possible reasons include:

• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

403 Forbidden (not_authorized)

{
  "error": "not_found",
  "message": "Frontdoor 3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c not found"
}

Possible reasons include:

• Invalid token: The token is not valid.
• The token does not grant access to the requested resource.
• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.