API service

This page is for the person who connects a program to the API.

Service state operations used by operators and load balancers.

getHealth

GET /api/health

Report that the service process is running.

Reports process liveness only. The operation never inspects a dependency, so a caller cannot use it to decide that the service can accept traffic. Use the readiness operation for that decision.

Authentication

No security scheme is declared. See the operation description.

Parameters

x-request-id

JSON

{
  "name": "x-request-id",
  "in": "header",
  "required": false,
  "style": "simple",
  "explode": false,
  "description": "Optional caller supplied correlation identifier. The server echoes the value and generates a UUID when the header is absent. A value outside the pattern below is rejected with a 400 problem.",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 128,
    "pattern": "^[A-Za-z0-9._-]+$"
  }
}

Responses

200

The service process is running.

JSON

{
  "description": "The service process is running.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/HealthReport"
      }
    }
  }
}

Schemas: HealthReport.

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

getReadiness

GET /api/ready

Report whether the service can accept traffic.

Reports the state of every startup requirement that the service can check. The current release validates configuration only, because no database or storage dependency exists yet. A later task adds a database check and a storage check to the same report.

Authentication

No security scheme is declared. See the operation description.

Parameters

x-request-id

JSON

{
  "name": "x-request-id",
  "in": "header",
  "required": false,
  "style": "simple",
  "explode": false,
  "description": "Optional caller supplied correlation identifier. The server echoes the value and generates a UUID when the header is absent. A value outside the pattern below is rejected with a 400 problem.",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 128,
    "pattern": "^[A-Za-z0-9._-]+$"
  }
}

detail

JSON

{
  "name": "detail",
  "in": "query",
  "required": false,
  "style": "form",
  "explode": true,
  "description": "Amount of readiness information to return. A summary report omits the detail text of each check.",
  "schema": {
    "type": "string",
    "enum": [
      "summary",
      "full"
    ]
  }
}

Responses

200

The service can accept traffic.

JSON

{
  "description": "The service can accept traffic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ReadinessReport"
      }
    }
  }
}

Schemas: ReadinessReport.

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

503

The service cannot accept traffic yet.

JSON

{
  "description": "The service cannot accept traffic yet.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

getSyncProtocol

GET /api/sync/protocol

Report the sync protocol versions that this server serves.

Lists every sync protocol version that the push and pull operations of this deployment accept. A client reads it before it pushes or pulls and sends nothing when its own version is not in the list. A server that answers 404 for this operation predates it and serves version 1 only. The answer holds no account or workspace data, so no session is needed.

Authentication

No security scheme is declared. See the operation description.

Parameters

x-request-id

JSON

{
  "name": "x-request-id",
  "in": "header",
  "required": false,
  "style": "simple",
  "explode": false,
  "description": "Optional caller supplied correlation identifier. The server echoes the value and generates a UUID when the header is absent. A value outside the pattern below is rejected with a 400 problem.",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 128,
    "pattern": "^[A-Za-z0-9._-]+$"
  }
}

Responses

200

The sync protocol versions that this server serves.

JSON

{
  "description": "The sync protocol versions that this server serves.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/SyncProtocolReport"
      }
    }
  }
}

Schemas: SyncProtocolReport.

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

getRootHealth

GET /health

Report that the service process is running, at the root address.

Serves the same answer as the liveness operation at the API address. A load balancer and an orchestrator usually probe a fixed root path, so the service answers that address too. The server calls one implementation for both addresses, so the two answers cannot disagree. Reports process liveness only, and never inspects a dependency.

Authentication

No security scheme is declared. See the operation description.

Parameters

x-request-id

JSON

{
  "name": "x-request-id",
  "in": "header",
  "required": false,
  "style": "simple",
  "explode": false,
  "description": "Optional caller supplied correlation identifier. The server echoes the value and generates a UUID when the header is absent. A value outside the pattern below is rejected with a 400 problem.",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 128,
    "pattern": "^[A-Za-z0-9._-]+$"
  }
}

Responses

200

The service process is running.

JSON

{
  "description": "The service process is running.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/HealthReport"
      }
    }
  }
}

Schemas: HealthReport.

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

getRootReadiness

GET /ready

Report whether the service can accept traffic, at the root address.

Serves the same answer as the readiness operation at the API address. A load balancer and an orchestrator usually probe a fixed root path, so the service answers that address too. The server calls one implementation for both addresses, so the two answers cannot disagree. Reports the state of every startup requirement, and reports the stop of the process while it drains.

Authentication

No security scheme is declared. See the operation description.

Parameters

x-request-id

JSON

{
  "name": "x-request-id",
  "in": "header",
  "required": false,
  "style": "simple",
  "explode": false,
  "description": "Optional caller supplied correlation identifier. The server echoes the value and generates a UUID when the header is absent. A value outside the pattern below is rejected with a 400 problem.",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 128,
    "pattern": "^[A-Za-z0-9._-]+$"
  }
}

detail

JSON

{
  "name": "detail",
  "in": "query",
  "required": false,
  "style": "form",
  "explode": true,
  "description": "Amount of readiness information to return. A summary report omits the detail text of each check.",
  "schema": {
    "type": "string",
    "enum": [
      "summary",
      "full"
    ]
  }
}

Responses

200

The service can accept traffic.

JSON

{
  "description": "The service can accept traffic.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ReadinessReport"
      }
    }
  }
}

Schemas: ReadinessReport.

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

503

The service cannot accept traffic yet.

JSON

{
  "description": "The service cannot accept traffic yet.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.